Debian Codegraph @

include/deal.II/dofs/dof_tools.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_dof_tools_h
16 #define dealii_dof_tools_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/index_set.h>
23 #include <deal.II/base/point.h>
24
25 #include <deal.II/dofs/dof_handler.h>
26
27 #include <deal.II/fe/component_mask.h>
28
29 #include <deal.II/lac/affine_constraints.h>
30 #include <deal.II/lac/sparsity_pattern_base.h>
31
32 #include <map>
33 #include <ostream>
34 #include <set>
35 #include <vector>
36
37
38 DEAL_II_NAMESPACE_OPEN
39
40 // Forward declarations
41 #ifndef DOXYGEN
42 class BlockMask;
43 template <int dim, typename RangeNumberType>
44 class Function;
45 template <int dim, int spacedim>
46 class FiniteElement;
47 namespace hp
48 {
49 template <int dim, int spacedim>
50 class MappingCollection;
51 template <int dim, int spacedim>
52 class FECollection;
53 } // namespace hp
54 template <typename MeshType>
55 DEAL_II_CXX20_REQUIRES(concepts::is_triangulation_or_dof_handler<MeshType>)
56 class InterGridMap;
57 template <int dim, int spacedim>
58 class Mapping;
59 template <int dim, class T>
60 class Table;
61 template <typename Number>
62 class Vector;
63
64 namespace GridTools
65 {
66 template <typename CellIterator>
67 struct PeriodicFacePair;
68 }
69
70 namespace DoFTools
71 {
72 namespace internal
73 {
74 /*
75 * Default value of the face_has_flux_coupling parameter of
76 * make_flux_sparsity_pattern. Defined here (instead of using a default
77 * lambda in the parameter list) to avoid a bug in gcc where the same lambda
78 * gets defined multiple times.
79 */
80 template <int dim, int spacedim>
81 inline bool
82 always_couple_on_faces(
83 const typename DoFHandler<dim, spacedim>::active_cell_iterator &,
84 const unsigned int)
85 {
86 return true;
87 }
88 } // namespace internal
89 } // namespace DoFTools
90
91 #endif
92
93 /**
94 * This is a collection of functions operating on, and manipulating the numbers
95 * of degrees of freedom. The documentation of the member functions will provide
96 * more information, but for functions that exist in multiple versions, there
97 * are sections in this global documentation stating some commonalities.
98 *
99 * <h3>Setting up sparsity patterns</h3>
100 *
101 * When assembling system matrices, the entries are usually of the form $a_{ij}
102 * = a(\phi_i, \phi_j)$, where $a$ is a bilinear functional, often an integral.
103 * When using sparse matrices, we therefore only need to reserve space for those
104 * $a_{ij}$ only, which are nonzero, which is the same as to say that the basis
105 * functions $\phi_i$ and $\phi_j$ have a nonempty intersection of their
106 * support. Since the support of basis functions is bound only on cells on which
107 * they are located or to which they are adjacent, to determine the sparsity
108 * pattern it is sufficient to loop over all cells and connect all basis
109 * functions on each cell with all other basis functions on that cell. There
110 * may be finite elements for which not all basis functions on a cell connect
111 * with each other, but no use of this case is made since no examples where this
112 * occurs are known to the author.
113 *
114 *
115 * <h3>DoF numberings on boundaries</h3>
116 *
117 * When projecting the traces of functions to the boundary or parts thereof, one
118 * needs to build matrices and vectors that act only on those degrees of freedom
119 * that are located on the boundary, rather than on all degrees of freedom. One
120 * could do that by simply building matrices in which the entries for all
121 * interior DoFs are zero, but such matrices are always very rank deficient and
122 * not very practical to work with.
123 *
124 * What is needed instead in this case is a numbering of the boundary degrees of
125 * freedom, i.e. we should enumerate all the degrees of freedom that are sitting
126 * on the boundary, and exclude all other (interior) degrees of freedom. The
127 * map_dof_to_boundary_indices() function does exactly this: it provides a
128 * vector with as many entries as there are degrees of freedom on the whole
129 * domain, with each entry being the number in the numbering of the boundary or
130 * numbers::invalid_dof_index if the dof is not on the boundary.
131 *
132 * With this vector, one can get, for any given degree of freedom, a unique
133 * number among those DoFs that sit on the boundary; or, if your DoF was
134 * interior to the domain, the result would be numbers::invalid_dof_index. We
135 * need this mapping, for example, to build the
136 * @ref GlossMassMatrix "mass matrix"
137 * on the boundary (for this, see make_boundary_sparsity_pattern()
138 * function, the corresponding section below, as well as the MatrixCreator
139 * namespace documentation).
140 *
141 * Actually, there are two map_dof_to_boundary_indices() functions, one
142 * producing a numbering for all boundary degrees of freedom and one producing a
143 * numbering for only parts of the boundary, namely those parts for which the
144 * boundary indicator is listed in a set of indicators given to the function.
145 * The latter case is needed if, for example, we would only want to project the
146 * boundary values for the Dirichlet part of the boundary. You then give the
147 * function a list of boundary indicators referring to Dirichlet parts on which
148 * the projection is to be performed. The parts of the boundary on which you
149 * want to project need not be contiguous; however, it is not guaranteed that
150 * the indices of each of the boundary parts are continuous, i.e. the indices of
151 * degrees of freedom on different parts may be intermixed.
152 *
153 * Degrees of freedom on the boundary but not on one of the specified boundary
154 * parts are given the index numbers::invalid_dof_index, as if they were in the
155 * interior. If no boundary indicator was given or if no face of a cell has a
156 * boundary indicator contained in the given list, the vector of new indices
157 * consists solely of numbers::invalid_dof_index.
158 *
159 * (As a side note, for corner cases: The question what a degree of freedom on
160 * the boundary is, is not so easy. It should really be a degree of freedom of
161 * which the respective basis function has nonzero values on the boundary. At
162 * least for Lagrange elements this definition is equal to the statement that
163 * the off-point, or what deal.II calls support_point, of the shape function,
164 * i.e. the point where the function assumes its nominal value (for Lagrange
165 * elements this is the point where it has the function value 1), is located on
166 * the boundary. We do not check this directly, the criterion is rather defined
167 * through the information the finite element class gives: the FiniteElement
168 * class defines the numbers of basis functions per vertex, per line, and so on
169 * and the basis functions are numbered after this information; a basis function
170 * is to be considered to be on the face of a cell (and thus on the boundary if
171 * the cell is at the boundary) according to it belonging to a vertex, line, etc
172 * but not to the interior of the cell. The finite element uses the same
173 * cell-wise numbering so that we can say that if a degree of freedom was
174 * numbered as one of the dofs on lines, we assume that it is located on the
175 * line. Where the off-point actually is, is a secret of the finite element
176 * (well, you can ask it, but we don't do it here) and not relevant in this
177 * context.)
178 *
179 *
180 * <h3>Setting up sparsity patterns for boundary matrices</h3>
181 *
182 * In some cases, one wants to only work with DoFs that sit on the boundary. One
183 * application is, for example, if rather than interpolating non- homogeneous
184 * boundary values, one would like to project them. For this, we need two
185 * things: a way to identify nodes that are located on (parts of) the boundary,
186 * and a way to build matrices out of only degrees of freedom that are on the
187 * boundary (i.e. much smaller matrices, in which we do not even build the large
188 * zero block that stems from the fact that most degrees of freedom have no
189 * support on the boundary of the domain). The first of these tasks is done by
190 * the map_dof_to_boundary_indices() function (described above).
191 *
192 * The second part requires us first to build a sparsity pattern for the
193 * couplings between boundary nodes, and then to actually build the components
194 * of this matrix. While actually computing the entries of these small boundary
195 * matrices is discussed in the MatrixCreator namespace, the creation of the
196 * sparsity pattern is done by the create_boundary_sparsity_pattern() function.
197 * For its work, it needs to have a numbering of all those degrees of freedom
198 * that are on those parts of the boundary that we are interested in. You can
199 * get this from the map_dof_to_boundary_indices() function. It then builds the
200 * sparsity pattern corresponding to integrals like $\int_\Gamma
201 * \varphi_{b2d(i)} \varphi_{b2d(j)} dx$, where $i$ and $j$ are indices into the
202 * matrix, and $b2d(i)$ is the global DoF number of a degree of freedom sitting
203 * on a boundary (i.e., $b2d$ is the inverse of the mapping returned by
204 * map_dof_to_boundary_indices() function).
205 *
206 * <h3>DoF coupling between surface triangulations and bulk triangulations</h3>
207 *
208 * When working with Triangulation and DoFHandler objects of different
209 * co-dimension, such as a `Triangulation<2,3>`, describing (part of) the
210 * boundary of a `Triangulation<3>`, and their corresponding DoFHandler objects,
211 * one often needs to build a one-to-one matching between the degrees of freedom
212 * that live on the surface Triangulation and those that live on the boundary of
213 * the bulk Triangulation. The GridGenerator::extract_boundary_mesh() function
214 * returns a mapping of surface cell iterators to face iterators, that can be
215 * used by the function map_boundary_to_bulk_dof_iterators() to construct a map
216 * between cell iterators of the surface DoFHandler, and the corresponding pair
217 * of cell iterator and face index of the bulk DoFHandler. Such map can be used
218 * to initialize FEValues and FEFaceValues for the corresponding DoFHandler
219 * objects. Notice that one must still ensure that the ordering of the
220 * quadrature points coincide in the two objects, in order to build a coupling
221 * matrix between the two sytesm.
222 *
223 * @ingroup dofs
224 */
225 namespace DoFTools
226 {
227 /**
228 * The flags used in tables by certain <tt>make_*_pattern</tt> functions to
229 * describe whether two components of the solution couple in the bilinear
230 * forms corresponding to cell or face terms. An example of using these
231 * flags is shown in the introduction of step-46.
232 *
233 * In the descriptions of the individual elements below, remember that these
234 * flags are used as elements of tables of size FiniteElement::n_components
235 * times FiniteElement::n_components where each element indicates whether
236 * two components do or do not couple.
237 */
238 enum Coupling
239 {
240 /**
241 * Two components do not couple.
242 */
243 none,
244 /**
245 * Two components do couple.
246 */
247 always,
248 /**
249 * Two components couple only if their shape functions are both nonzero on
250 * a given face. This flag is only used when computing integrals over
251 * faces of cells, e.g., in DoFTools::make_flux_sparsity_pattern().
252 * Use Coupling::always in general cases where gradients etc. occur on face
253 * integrals.
254 */
255 nonzero
256 };
257
258 /**
259 * @name DoF couplings
260 * @{
261 */
262
263 /**
264 * Map a coupling table from the user friendly organization by components to
265 * the organization by blocks.
266 *
267 * The return vector will be initialized to the correct length inside this
268 * function.
269 */
270 template <int dim, int spacedim>
271 void
272 convert_couplings_to_blocks(const DoFHandler<dim, spacedim> &dof_handler,
273 const Table<2, Coupling> &table_by_component,
274 std::vector<Table<2, Coupling>> &tables_by_block);
275
276 /**
277 * Given a finite element and a table how the vector components of it couple
278 * with each other, compute and return a table that describes how the
279 * individual shape functions couple with each other.
280 */
281 template <int dim, int spacedim>
282 Table<2, Coupling>
283 dof_couplings_from_component_couplings(
284 const FiniteElement<dim, spacedim> &fe,
285 const Table<2, Coupling> &component_couplings);
286
287 /**
288 * Same function as above for a collection of finite elements, returning a
289 * collection of tables.
290 *
291 * The function currently treats DoFTools::Couplings::nonzero the same as
292 * DoFTools::Couplings::always .
293 */
294 template <int dim, int spacedim>
295 std::vector<Table<2, Coupling>>
296 dof_couplings_from_component_couplings(
297 const hp::FECollection<dim, spacedim> &fe,
298 const Table<2, Coupling> &component_couplings);
299 /** @} */
300
301 /**
302 * @name Sparsity pattern generation
303 * @{
304 */
305
306 /**
307 * Compute which entries of a matrix built on the given @p dof_handler may
308 * possibly be nonzero, and create a sparsity pattern object that represents
309 * these nonzero locations.
310 *
311 * This function computes the possible positions of non-zero entries in the
312 * global system matrix by <i>simulating</i> which entries one would write
313 * to during the actual assembly of a matrix. For this, the function assumes
314 * that each finite element basis function is non-zero on a cell only if its
315 * degree of freedom is associated with the interior, a face, an edge or a
316 * vertex of this cell. As a result, a matrix entry $A_{ij}$ that is
317 * computed from two basis functions $\varphi_i$ and $\varphi_j$ with
318 * (global) indices $i$ and $j$ (for example, using a bilinear form
319 * $A_{ij}=a(\varphi_i,\varphi_j)$) can be non-zero only if these shape
320 * functions correspond to degrees of freedom that are defined on at least
321 * one common cell. Therefore, this function just loops over all cells,
322 * figures out the global indices of all degrees of freedom, and presumes
323 * that all matrix entries that couple any of these indices will result in a
324 * nonzero matrix entry. These will then be added to the sparsity pattern.
325 * As this process of generating the sparsity pattern does not take into
326 * account the equation to be solved later on, the resulting sparsity
327 * pattern is symmetric.
328 *
329 * This algorithm makes no distinction between shape functions on each cell,
330 * i.e., it simply couples all degrees of freedom on a cell with all other
331 * degrees of freedom on a cell. This is often the case, and always a safe
332 * assumption. However, if you know something about the structure of your
333 * operator and that it does not couple certain shape functions with certain
334 * test functions, then you can get a sparser sparsity pattern by calling a
335 * variant of the current function described below that allows to specify
336 * which vector components couple with which other vector components.
337 *
338 * The method described above lives on the assumption that coupling between
339 * degrees of freedom only happens if shape functions overlap on at least
340 * one cell. This is the case with most usual finite element formulations
341 * involving conforming elements. However, for formulations such as the
342 * Discontinuous Galerkin finite element method, the bilinear form contains
343 * terms on interfaces between cells that couple shape functions that live
344 * on one cell with shape functions that live on a neighboring cell. The
345 * current function would not see these couplings, and would consequently
346 * not allocate entries in the sparsity pattern. You would then get into
347 * trouble during matrix assembly because you try to write into matrix
348 * entries for which no space has been allocated in the sparsity pattern.
349 * This can be avoided by calling the DoFTools::make_flux_sparsity_pattern()
350 * function instead, which takes into account coupling between degrees of
351 * freedom on neighboring cells.
352 *
353 * There are other situations where bilinear forms contain non-local terms,
354 * for example in treating integral equations. These require different
355 * methods for building the sparsity patterns that depend on the exact
356 * formulation of the problem. You will have to do this yourself then.
357 *
358 * @param[in] dof_handler The DoFHandler object that describes which degrees
359 * of freedom live on which cells.
360 *
361 * @param[out] sparsity_pattern The sparsity pattern to be filled with
362 * entries.
363 *
364 * @param[in] constraints The process for generating entries described above
365 * is purely local to each cell. Consequently, the sparsity pattern does
366 * not provide for matrix entries that will only be written into during
367 * the elimination of hanging nodes or other constraints. They have to be
368 * taken care of by a subsequent call to AffineConstraints::condense().
369 * Alternatively, the constraints on degrees of freedom can already be
370 * taken into account at the time of creating the sparsity pattern. For
371 * this, pass the AffineConstraints object as the third argument to the
372 * current function. No call to AffineConstraints::condense() is then
373 * necessary. This process is explained in step-6, step-27, and other
374 * tutorial programs.
375 *
376 * @param[in] keep_constrained_dofs In case the constraints are already
377 * taken care of in this function by passing in a AffineConstraints object,
378 * it is possible to abandon some off-diagonal entries in the sparsity
379 * pattern if these entries will also not be written into during the actual
380 * assembly of the matrix this sparsity pattern later serves. Specifically,
381 * when using an assembly method that uses
382 * AffineConstraints::distribute_local_to_global(), no entries will ever be
383 * written into those matrix rows or columns that correspond to constrained
384 * degrees of freedom. In such cases, you can set the argument @p
385 * keep_constrained_dofs to @p false to avoid allocating these entries in
386 * the sparsity pattern.
387 *
388 * @param[in] subdomain_id If specified, the sparsity pattern is built only
389 * on cells that have a subdomain_id equal to the given argument. This is
390 * useful in parallel contexts where the matrix and sparsity pattern (for
391 * example a TrilinosWrappers::SparsityPattern) may be distributed and not
392 * every MPI process needs to build the entire sparsity pattern; in that
393 * case, it is sufficient if every process only builds that part of the
394 * sparsity pattern that corresponds to the subdomain_id for which it is
395 * responsible. This feature is used in step-32. (This argument is not
396 * usually needed for objects of type parallel::distributed::Triangulation
397 * because the current function only loops over locally owned cells anyway;
398 * thus, this argument typically only makes sense if you want to use the
399 * subdomain_id for anything other than indicating which processor owns a
400 * cell, for example which geometric component of the domain a cell belongs
401 * to.)
402 *
403 * @note The actual type of the sparsity pattern may be SparsityPattern,
404 * DynamicSparsityPattern, BlockSparsityPattern,
405 * BlockDynamicSparsityPattern, or any other class that satisfies similar
406 * requirements. It is assumed that the size of the sparsity pattern matches
407 * the number of degrees of freedom and that enough unused nonzero entries
408 * are left to fill the sparsity pattern if the sparsity pattern is of
409 * "static" kind (see
410 * @ref Sparsity
411 * for more information on what this means). The nonzero entries generated
412 * by this function are added to possible previous content of the object,
413 * i.e., previously added entries are not removed.
414 *
415 * @note If the sparsity pattern is represented by an object of type
416 * SparsityPattern (as opposed to, for example, DynamicSparsityPattern), you
417 * need to remember using SparsityPattern::compress() after generating the
418 * pattern.
419 *
420 * @ingroup constraints
421 */
422 template <int dim, int spacedim, typename number = double>
423 void
424 make_sparsity_pattern(
425 const DoFHandler<dim, spacedim> &dof_handler,
426 SparsityPatternBase &sparsity_pattern,
427 const AffineConstraints<number> &constraints = {},
428 const bool keep_constrained_dofs = true,
429 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
430
431 /**
432 * Compute which entries of a matrix built on the given @p dof_handler may
433 * possibly be nonzero, and create a sparsity pattern object that represents
434 * these nonzero locations.
435 *
436 * This function is a simple variation on the previous
437 * make_sparsity_pattern() function (see there for a description of all of
438 * the common arguments), but it provides functionality for vector finite
439 * elements that allows to be more specific about which variables couple in
440 * which equation.
441 *
442 * For example, if you wanted to solve the Stokes equations,
443 *
444 * @f{align*}{
445 * -\Delta \mathbf u + \nabla p &= 0,\\ \text{div}\ u &= 0
446 * @f}
447 *
448 * in two space dimensions, using stable Q2/Q1 mixed elements (using the
449 * FESystem class), then you don't want all degrees of freedom to couple in
450 * each equation. More specifically, in the first equation, only $u_x$ and
451 * $p$ appear; in the second equation, only $u_y$ and $p$ appear; and in the
452 * third equation, only $u_x$ and $u_y$ appear. (Note that this discussion
453 * only talks about vector components of the solution variable and the
454 * different equation, and has nothing to do with degrees of freedom, or in
455 * fact with any kind of discretization.) We can describe this by the
456 * following pattern of "couplings":
457 *
458 * @f[
459 * \left[
460 * \begin{array}{ccc}
461 * 1 & 0 & 1 \\
462 * 0 & 1 & 1 \\
463 * 1 & 1 & 0
464 * \end{array}
465 * \right]
466 * @f]
467 *
468 * where "1" indicates that two variables (i.e., vector components of the
469 * FESystem) couple in the respective equation, and a "0" means no coupling.
470 * These zeros imply that upon discretization via a standard finite element
471 * formulation, we will not write entries into the matrix that, for example,
472 * couple pressure test functions with pressure shape functions (and similar
473 * for the other zeros above). It is then a waste to allocate memory for
474 * these entries in the matrix and the sparsity pattern, and you can avoid
475 * this by creating a mask such as the one above that describes this to the
476 * (current) function that computes the sparsity pattern. As stated above,
477 * the mask shown above refers to components of the composed FESystem,
478 * rather than to degrees of freedom or shape functions.
479 *
480 * This function is designed to accept a coupling pattern, like the one
481 * shown above, through the @p couplings parameter, which contains values of
482 * type #Coupling. It builds the matrix structure just like the previous
483 * function, but does not create matrix elements if not specified by the
484 * coupling pattern. If the couplings are symmetric, then so will be the
485 * resulting sparsity pattern.
486 *
487 * There is a complication if some or all of the shape functions of the
488 * finite element in use are non-zero in more than one component (in deal.II
489 * speak: they are
490 * @ref GlossPrimitive "non-primitive finite elements").
491 * In this case, the coupling element corresponding to the first non-zero
492 * component is taken and additional ones for this component are ignored.
493 *
494 * @ingroup constraints
495 */
496 template <int dim, int spacedim, typename number = double>
497 void
498 make_sparsity_pattern(
499 const DoFHandler<dim, spacedim> &dof_handler,
500 const Table<2, Coupling> &coupling,
501 SparsityPatternBase &sparsity_pattern,
502 const AffineConstraints<number> &constraints = {},
503 const bool keep_constrained_dofs = true,
504 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
505
506 /**
507 * Construct a sparsity pattern that allows coupling degrees of freedom on
508 * two different but related meshes.
509 *
510 * The idea is that if the two given DoFHandler objects correspond to two
511 * different meshes (and potentially to different finite elements used on
512 * these cells), but that if the two triangulations they are based on are
513 * derived from the same coarse mesh through hierarchical refinement, then
514 * one may set up a problem where one would like to test shape functions
515 * from one mesh against the shape functions from another mesh. In
516 * particular, this means that shape functions from a cell on the first mesh
517 * are tested against those on the second cell that are located on the
518 * corresponding cell; this correspondence is something that the
519 * IntergridMap class can determine.
520 *
521 * This function then constructs a sparsity pattern for which the degrees of
522 * freedom that represent the rows come from the first given DoFHandler,
523 * whereas the ones that correspond to columns come from the second
524 * DoFHandler.
525 */
526 template <int dim, int spacedim>
527 void
528 make_sparsity_pattern(const DoFHandler<dim, spacedim> &dof_row,
529 const DoFHandler<dim, spacedim> &dof_col,
530 SparsityPatternBase &sparsity);
531
532 /**
533 * Compute which entries of a matrix built on the given @p dof_handler may
534 * possibly be nonzero, and create a sparsity pattern object that represents
535 * these nonzero locations. This function is a variation of the
536 * make_sparsity_pattern() functions above in that it assumes that the
537 * bilinear form you want to use to generate the matrix also contains terms
538 * that integrate over the <i>faces</i> between cells (i.e., it contains
539 * "fluxes" between cells, explaining the name of the function).
540 *
541 * This function is useful for Discontinuous Galerkin methods where the
542 * standard make_sparsity_pattern() function would only create nonzero
543 * entries for all degrees of freedom on one cell coupling to all other
544 * degrees of freedom on the same cell; however, in DG methods, all or some
545 * degrees of freedom on each cell also couple to the degrees of freedom on
546 * other cells connected to the current one by a common face. The current
547 * function also creates the nonzero entries in the matrix resulting from
548 * these additional couplings. In other words, this function computes a
549 * strict super-set of nonzero entries compared to the work done by
550 * make_sparsity_pattern().
551 *
552 * @param[in] dof_handler The DoFHandler object that describes which degrees
553 * of freedom live on which cells.
554 *
555 * @param[out] sparsity_pattern The sparsity pattern to be filled with
556 * entries.
557 *
558 * @note The actual type of the sparsity pattern may be SparsityPattern,
559 * DynamicSparsityPattern, BlockSparsityPattern,
560 * BlockDynamicSparsityPattern, or any other class that satisfies similar
561 * requirements. It is assumed that the size of the sparsity pattern matches
562 * the number of degrees of freedom and that enough unused nonzero entries
563 * are left to fill the sparsity pattern if the sparsity pattern is of
564 * "static" kind (see
565 * @ref Sparsity
566 * for more information on what this means). The nonzero entries generated
567 * by this function are added to possible previous content of the object,
568 * i.e., previously added entries are not removed.
569 *
570 * @note If the sparsity pattern is represented by an object of type
571 * SparsityPattern (as opposed to, for example, DynamicSparsityPattern), you
572 * need to remember using SparsityPattern::compress() after generating the
573 * pattern.
574 *
575 * @ingroup constraints
576 */
577 template <int dim, int spacedim>
578 void
579 make_flux_sparsity_pattern(const DoFHandler<dim, spacedim> &dof_handler,
580 SparsityPatternBase &sparsity_pattern);
581
582 /**
583 * This function does essentially the same as the other
584 * make_flux_sparsity_pattern() function but allows the specification of a
585 * number of additional arguments. These carry the same meaning as discussed
586 * in the first make_sparsity_pattern() function above.
587 *
588 * @ingroup constraints
589 */
590 template <int dim, int spacedim, typename number>
591 void
592 make_flux_sparsity_pattern(
593 const DoFHandler<dim, spacedim> &dof_handler,
594 SparsityPatternBase &sparsity_pattern,
595 const AffineConstraints<number> &constraints,
596 const bool keep_constrained_dofs = true,
597 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
598
599
600 /**
601 * This function does essentially the same as the other
602 * make_flux_sparsity_pattern() function but allows the specification of
603 * coupling matrices that state which components of the solution variable
604 * couple in each of the equations you are discretizing. This works in
605 * complete analogy as discussed in the second make_sparsity_pattern()
606 * function above.
607 *
608 * In fact, this function takes two such masks, one describing which
609 * variables couple with each other in the cell integrals that make up your
610 * bilinear form, and which variables couple with each other in the face
611 * integrals. If you passed masks consisting of only 1s to both of these,
612 * then you would get the same sparsity pattern as if you had called the
613 * first of the make_flux_sparsity_pattern() functions above. By setting
614 * some of the entries of these masks to zeros, you can get a sparser
615 * sparsity pattern.
616 *
617 * @ingroup constraints
618 */
619 template <int dim, int spacedim>
620 void
621 make_flux_sparsity_pattern(
622 const DoFHandler<dim, spacedim> &dof,
623 SparsityPatternBase &sparsity,
624 const Table<2, Coupling> &cell_integrals_mask,
625 const Table<2, Coupling> &face_integrals_mask,
626 const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
627
628
629 /**
630 * This function does essentially the same as the previous
631 * make_flux_sparsity_pattern() function but allows the application of an
632 * AffineConstraints object. This is useful in the case where some
633 * components of a finite element are continuous and some discontinuous,
634 * allowing constraints to be imposed on the continuous part while also
635 * building the flux terms needed for the discontinuous part.
636 *
637 * The optional @p face_has_flux_coupling can be used to specify on which
638 * faces flux couplings occur. This allows for creating a sparser pattern when
639 * using a bilinear form where flux terms only appear on a subset of the faces
640 * in the triangulation. By default flux couplings are added over all internal
641 * faces. @p face_has_flux_coupling should be a function that takes an
642 * active_cell_iterator and a face index and should return true if there is a
643 * flux coupling over the face. When using DoFHandler we could, for example,
644 * use
645 *
646 * @code
647 * auto face_has_flux_coupling =
648 * [](const typename DoFHandler<dim>::active_cell_iterator &cell,
649 * const unsigned int face_index) {
650 * const Point<dim> &face_center = cell->face(face_index)->center();
651 * return 0 < face_center[0];
652 * };
653 * @endcode
654 */
655 template <int dim, int spacedim, typename number>
656 void
657 make_flux_sparsity_pattern(
658 const DoFHandler<dim, spacedim> &dof,
659 SparsityPatternBase &sparsity,
660 const AffineConstraints<number> &constraints,
661 const bool keep_constrained_dofs,
662 const Table<2, Coupling> &couplings,
663 const Table<2, Coupling> &face_couplings,
664 const types::subdomain_id subdomain_id,
665 const std::function<
666 bool(const typename DoFHandler<dim, spacedim>::active_cell_iterator &,
667 const unsigned int)> &face_has_flux_coupling =
668 &internal::always_couple_on_faces<dim, spacedim>);
669
670 /**
671 * Create the sparsity pattern for boundary matrices. See the general
672 * documentation of this class for more information.
673 *
674 * The function does essentially what the other make_sparsity_pattern()
675 * functions do, but assumes that the bilinear form that is used to build
676 * the matrix does not consist of domain integrals, but only of integrals
677 * over the boundary of the domain.
678 */
679 template <int dim, int spacedim>
680 void
681 make_boundary_sparsity_pattern(
682 const DoFHandler<dim, spacedim> &dof,
683 const std::vector<types::global_dof_index> &dof_to_boundary_mapping,
684 SparsityPatternBase &sparsity_pattern);
685
686 /**
687 * This function is a variation of the previous
688 * make_boundary_sparsity_pattern() function in which we assume that the
689 * boundary integrals that will give rise to the matrix extends only over
690 * those parts of the boundary whose boundary indicators are listed in the
691 * @p boundary_ids argument to this function.
692 *
693 * This function could have been written by passing a @p set of boundary_id
694 * numbers. However, most of the functions throughout deal.II dealing with
695 * boundary indicators take a mapping of boundary indicators and the
696 * corresponding boundary function, i.e., a std::map<types::boundary_id, const
697 * Function<spacedim,number>*> argument. Correspondingly, this function does
698 * the same, though the actual boundary function is ignored here.
699 * (Consequently, if you don't have any such boundary functions, just create a
700 * map with the boundary indicators you want and set the function pointers to
701 * null pointers).
702 */
703 template <int dim, int spacedim, typename number>
704 void
705 make_boundary_sparsity_pattern(
706 const DoFHandler<dim, spacedim> &dof,
707 const std::map<types::boundary_id, const Function<spacedim, number> *>
708 &boundary_ids,
709 const std::vector<types::global_dof_index> &dof_to_boundary_mapping,
710 SparsityPatternBase &sparsity);
711
712 /**
713 * @}
714 */
715
716 /**
717 * @name Hanging nodes and other constraints
718 * @{
719 */
720
721 /**
722 * Compute the constraints resulting from the presence of hanging nodes.
723 * Hanging nodes are best explained using a small picture:
724 *
725 * @image html hanging_nodes.png
726 *
727 * In order to make a finite element function globally continuous, we have
728 * to make sure that the dark red nodes have values that are compatible with
729 * the adjacent yellow nodes, so that the function has no jump when coming
730 * from the small cells to the large one at the top right. We therefore have
731 * to add conditions that constrain those "hanging nodes".
732 *
733 * The object into which these are inserted is later used to condense the
734 * global system matrix and right hand side, and to extend the solution
735 * vectors from the true degrees of freedom also to the constraint nodes.
736 * This function is explained in detail in the
737 * @ref step_6 "step-6"
738 * tutorial program and is used in almost all following programs as well.
739 *
740 * This function does not clear the AffineConstraints object before use, in
741 * order to allow adding constraints from different sources to the same
742 * object. You therefore need to make sure it contains only constraints you
743 * still want; otherwise call the AffineConstraints::clear() function.
744 * Since this function does not check if it would add cycles in
745 * @p constraints, it is recommended to call this function prior to other
746 * functions that constrain DoFs with respect to others such as
747 * make_periodicity_constraints().
748 * This function does not close the object since you may want to
749 * enter other constraints later on yourself.
750 *
751 * Using a DoFHandler with hp-capabilities, we consider constraints due to
752 * different finite elements used on two sides of a face between cells as
753 * hanging nodes as well. In other words, in hp-mode, this function computes
754 * all constraints due to differing mesh sizes (h) or polynomial degrees (p)
755 * between adjacent cells.
756 *
757 * @ingroup constraints
758 */
759 template <int dim, int spacedim, typename number>
760 void
761 make_hanging_node_constraints(const DoFHandler<dim, spacedim> &dof_handler,
762 AffineConstraints<number> &constraints);
763
764 /**
765 * This function is used when different variables in a problem are
766 * discretized on different grids, where one grid is strictly coarser than
767 * the other. An example are optimization problems where the control
768 * variable is often discretized on a coarser mesh than the state variable.
769 *
770 * The function's result can be stated as follows mathematically: Let ${\cal
771 * T}_0$ and ${\cal T}_1$ be two meshes where ${\cal T}_1$ results from
772 * ${\cal T}_0$ strictly by refining or leaving alone the cells of ${\cal
773 * T}_0$. Using the same finite element on both, there are function spaces
774 * ${\cal V}_0$ and ${\cal V}_1$ associated with these meshes. Then every
775 * function $v_0 \in {\cal V}_0$ can of course also be represented exactly
776 * in ${\cal V}_1$ since by construction ${\cal V}_0 \subset {\cal V}_1$.
777 * However, not every function in ${\cal V}_1$ can be expressed as a linear
778 * combination of the shape functions of ${\cal V}_0$. The functions that
779 * can be represented lie in a homogeneous subspace of ${\cal V}_1$ (namely,
780 * ${\cal V}_0$, of course) and this subspace can be represented by a linear
781 * constraint of the form $CV=0$ where $V$ is the vector of nodal values of
782 * functions $v\in {\cal V}_1$. In other words, every function $v_h=\sum_j
783 * V_j \varphi_j^{(1)} \in {\cal V}_1$ that also satisfies $v_h\in {\cal
784 * V}_0$ automatically satisfies $CV=0$. This function computes the matrix
785 * $C$ in the form of a AffineConstraints object.
786 *
787 * The construction of these constraints is done as follows: for each of the
788 * degrees of freedom (i.e. shape functions) on the coarse grid, we compute
789 * its representation on the fine grid, i.e. how the linear combination of
790 * shape functions on the fine grid looks like that resembles the shape
791 * function on the coarse grid. From this information, we can then compute
792 * the constraints which have to hold if a solution of a linear equation on
793 * the fine grid shall be representable on the coarse grid. The exact
794 * algorithm how these constraints can be computed is rather complicated and
795 * is best understood by reading the source code, which contains many
796 * comments.
797 *
798 * The use of this function is as follows: it accepts as parameters two DoF
799 * Handlers, the first of which refers to the coarse grid and the second of
800 * which is the fine grid. On both, a finite element is represented by the
801 * DoF handler objects, which will usually have several vector components,
802 * which may belong to different base elements. The second and fourth
803 * parameter of this function therefore state which vector component on the
804 * coarse grid shall be used to restrict the stated component on the fine
805 * grid. The finite element used for the respective components on the two
806 * grids needs to be the same. An example may clarify this: consider an
807 * optimization problem with controls $q$ discretized on a coarse mesh and a
808 * state variable $u$ (and corresponding Lagrange multiplier $\lambda$)
809 * discretized on the fine mesh. These are discretized using piecewise
810 * constant discontinuous, continuous linear, and continuous linear
811 * elements, respectively. Only the parameter $q$ is represented on the
812 * coarse grid, thus the DoFHandler object on the coarse grid represents
813 * only one variable, discretized using piecewise constant discontinuous
814 * elements. Then, the parameter denoting the vector component on the coarse
815 * grid would be zero (the only possible choice, since the variable on the
816 * coarse grid is scalar). If the ordering of variables in the fine mesh
817 * FESystem is $u, q, \lambda$, then the fourth argument of the function
818 * corresponding to the vector component would be one (corresponding to the
819 * variable $q$; zero would be $u$, two would be $\lambda$).
820 *
821 * The function also requires an object of type IntergridMap representing
822 * how to get from the coarse mesh cells to the corresponding cells on the
823 * fine mesh. This could in principle be generated by the function itself
824 * from the two DoFHandler objects, but since it is probably available
825 * anyway in programs that use different meshes, the function simply takes
826 * it as an argument.
827 *
828 * The computed constraints are entered into a variable of type
829 * AffineConstraints; previous contents are not deleted.
830 */
831 template <int dim, int spacedim>
832 void
833 compute_intergrid_constraints(
834 const DoFHandler<dim, spacedim> &coarse_grid,
835 const unsigned int coarse_component,
836 const DoFHandler<dim, spacedim> &fine_grid,
837 const unsigned int fine_component,
838 const InterGridMap<DoFHandler<dim, spacedim>> &coarse_to_fine_grid_map,
839 AffineConstraints<double> &constraints);
840
841
842 /**
843 * This function generates a matrix such that when a vector of data with as
844 * many elements as there are degrees of freedom of this component on the
845 * coarse grid is multiplied to this matrix, we obtain a vector with as many
846 * elements as there are global degrees of freedom on the fine grid. All the
847 * elements of the other vector components of the finite element fields on
848 * the fine grid are not touched.
849 *
850 * Triangulation of the fine grid can be distributed. When called in
851 * parallel, each process has to have a copy of the coarse grid. In this
852 * case, function returns transfer representation for a set of locally owned
853 * cells.
854 *
855 * The output of this function is a compressed format that can be used to
856 * construct corresponding sparse transfer matrix.
857 */
858 template <int dim, int spacedim>
859 void
860 compute_intergrid_transfer_representation(
861 const DoFHandler<dim, spacedim> &coarse_grid,
862 const unsigned int coarse_component,
863 const DoFHandler<dim, spacedim> &fine_grid,
864 const unsigned int fine_component,
865 const InterGridMap<DoFHandler<dim, spacedim>> &coarse_to_fine_grid_map,
866 std::vector<std::map<types::global_dof_index, float>>
867 &transfer_representation);
868
869 /**
870 * @}
871 */
872
873
874 /**
875 * @name Periodic boundary conditions
876 * @{
877 */
878
879 /**
880 * Insert the (algebraic) constraints due to periodic boundary conditions
881 * into an AffineConstraints object @p constraints.
882 *
883 * Given a pair of not necessarily active boundary faces @p face_1 and @p
884 * face_2, this functions constrains all DoFs associated with the boundary
885 * described by @p face_1 to the respective DoFs of the boundary described
886 * by @p face_2. More precisely:
887 *
888 * If @p face_1 and @p face_2 are both active faces it adds the DoFs of @p
889 * face_1 to the list of constrained DoFs in @p constraints and adds
890 * entries to constrain them to the corresponding values of the DoFs on @p
891 * face_2. This happens on a purely algebraic level, meaning, the global DoF
892 * with (local face) index <tt>i</tt> on @p face_1 gets constraint to the
893 * DoF with (local face) index <tt>i</tt> on @p face_2 (possibly corrected
894 * for orientation, see below).
895 *
896 * Otherwise, if @p face_1 and @p face_2 are not active faces, this function
897 * loops recursively over the children of @p face_1 and @p face_2. If only
898 * one of the two faces is active, then we recursively iterate over the
899 * children of the non-active ones and make sure that the solution function
900 * on the refined side equals that on the non-refined face in much the same
901 * way as we enforce hanging node constraints at places where differently
902 * refined cells come together. (However, unlike hanging nodes, we do not
903 * enforce the requirement that there be only a difference of one refinement
904 * level between the two sides of the domain you would like to be periodic).
905 *
906 * This routine only constrains DoFs that are not already constrained. If
907 * this routine encounters a DoF that already is constrained (for instance
908 * by Dirichlet boundary conditions), the old setting of the constraint
909 * (dofs the entry is constrained to, inhomogeneities) is kept and nothing
910 * happens.
911 *
912 * The flags in the @p component_mask (see
913 * @ref GlossComponentMask)
914 * denote which components of the finite element space shall be constrained
915 * with periodic boundary conditions. If it is left as specified by the
916 * default value all components are constrained. If it is different from the
917 * default value, it is assumed that the number of entries equals the number
918 * of components of the finite element. This can be used to enforce
919 * periodicity in only one variable in a system of equations.
920 *
921 * Here, @p combined_orientation is the relative orientation of @p face_1 with
922 * respect to @p face_2. This is typically computed by
923 * GridTools::orthogonal_equality().
924 *
925 * Optionally a matrix @p matrix along with a std::vector @p
926 * first_vector_components can be specified that describes how DoFs on @p
927 * face_1 should be modified prior to constraining to the DoFs of @p face_2.
928 * Here, two declarations are possible: If the std::vector @p
929 * first_vector_components is non empty the matrix is interpreted as a @p
930 * dim $\times$ @p dim rotation matrix that is applied to all vector valued
931 * blocks listed in @p first_vector_components of the FESystem. If @p
932 * first_vector_components is empty the matrix is interpreted as an
933 * interpolation matrix with size no_face_dofs $\times$ no_face_dofs.
934 *
935 * This function makes sure that identity constraints don't create cycles
936 * in @p constraints.
937 *
938 * @p periodicity_factor can be used to implement Bloch periodic conditions
939 * (a.k.a. phase shift periodic conditions) of the form
940 * $\psi(\mathbf{r})=e^{-i\mathbf{k}\cdot\mathbf{r}}u(\mathbf{r})$
941 * where $u$ is periodic with the same periodicity as the crystal lattice and
942 * $\mathbf{k}$ is the wavevector, see
943 * [https://en.wikipedia.org/wiki/Bloch_wave](https://en.wikipedia.org/wiki/Bloch_wave).
944 * The solution at @p face_2 is equal to the solution at @p face_1 times
945 * @p periodicity_factor. For example, if the solution at @p face_1 is
946 * $\psi(0)$ and $\mathbf{d}$ is the corresponding point on @p face_2, then
947 * the solution at @p face_2 should be
948 * $\psi(d) = \psi(0)e^{-i \mathbf{k}\cdot \mathbf{d}}$. This condition can be
949 * implemented using
950 * $\mathrm{periodicity\_factor}=e^{-i \mathbf{k}\cdot \mathbf{d}}$.
951 *
952 * Detailed information can be found in the see
953 * @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions".
954 */
955 template <typename FaceIterator, typename number>
956 void
957 make_periodicity_constraints(
958 const FaceIterator &face_1,
959 const std_cxx20::type_identity_t<FaceIterator> &face_2,
960 AffineConstraints<number> &constraints,
961 const ComponentMask &component_mask = {},
962 const types::geometric_orientation combined_orientation =
963 numbers::default_geometric_orientation,
964 const FullMatrix<double> &matrix = FullMatrix<double>(),
965 const std::vector<unsigned int> &first_vector_components =
966 std::vector<unsigned int>(),
967 const number periodicity_factor = 1.);
968
969
970 /**
971 * Insert the (algebraic) constraints due to periodic boundary conditions
972 * into an AffineConstraints object @p constraints.
973 *
974 * This is the main high level interface for above low level variant of
975 * make_periodicity_constraints(). It takes a std::vector @p periodic_faces
976 * as argument and applies above make_periodicity_constraints() on each
977 * entry. @p periodic_faces can be created by
978 * GridTools::collect_periodic_faces.
979 *
980 * @note For DoFHandler objects that are built on a
981 * parallel::distributed::Triangulation object
982 * parallel::distributed::Triangulation::add_periodicity has to be called
983 * before calling this function..
984 *
985 * @see
986 * @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
987 * and step-45 for further information.
988 */
989 template <int dim, int spacedim, typename number>
990 void
991 make_periodicity_constraints(
992 const std::vector<GridTools::PeriodicFacePair<
993 typename DoFHandler<dim, spacedim>::cell_iterator>> &periodic_faces,
994 AffineConstraints<number> &constraints,
995 const ComponentMask &component_mask = {},
996 const std::vector<unsigned int> &first_vector_components =
997 std::vector<unsigned int>(),
998 const number periodicity_factor = 1.);
999
1000
1001
1002 /**
1003 * Insert the (algebraic) constraints due to periodic boundary conditions
1004 * into a AffineConstraints @p constraints.
1005 *
1006 * This function serves as a high level interface for the
1007 * make_periodicity_constraints() function.
1008 *
1009 * Define a 'first' boundary as all boundary faces having boundary_id @p
1010 * b_id1 and a 'second' boundary consisting of all faces belonging to @p
1011 * b_id2.
1012 *
1013 * This function tries to match all faces belonging to the first boundary
1014 * with faces belonging to the second boundary with the help of
1015 * orthogonal_equality(). More precisely, faces with coordinates only
1016 * differing in the @p direction component are identified.
1017 *
1018 * If this matching is successful it constrains all DoFs associated with the
1019 * 'first' boundary to the respective DoFs of the 'second' boundary
1020 * respecting the relative orientation of the two faces.
1021 *
1022 * @note This function is a convenience wrapper. It internally calls
1023 * GridTools::collect_periodic_faces() with the supplied parameters and
1024 * feeds the output to above make_periodicity_constraints() variant. If you
1025 * need more functionality use GridTools::collect_periodic_faces() directly.
1026 *
1027 * @see
1028 * @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
1029 * for further information.
1030 */
1031 template <int dim, int spacedim, typename number>
1032 void
1033 make_periodicity_constraints(const DoFHandler<dim, spacedim> &dof_handler,
1034 const types::boundary_id b_id1,
1035 const types::boundary_id b_id2,
1036 const unsigned int direction,
1037 AffineConstraints<number> &constraints,
1038 const ComponentMask &component_mask = {},
1039 const number periodicity_factor = 1.);
1040
1041
1042
1043 /**
1044 * Instead of defining a 'first' and 'second' boundary with the help of two
1045 * boundary_ids this function defines a 'left' boundary as all faces with
1046 * local face index <code>2*dimension</code> and boundary indicator @p b_id
1047 * and, similarly, a 'right' boundary consisting of all face with local face
1048 * index <code>2*dimension+1</code> and boundary indicator @p b_id. Faces with
1049 * coordinates only differing in the @p direction component are identified.
1050 *
1051 * @warning This version of make_periodicity_constraints will not work on
1052 * meshes with cells not in
1053 * @ref GlossCombinedOrientation "the default orientation".
1054 *
1055 * @note This function is a convenience wrapper. It internally calls
1056 * GridTools::collect_periodic_faces() with the supplied parameters and
1057 * feeds the output to above make_periodicity_constraints() variant. If you
1058 * need more functionality use GridTools::collect_periodic_faces() directly.
1059 *
1060 * @see
1061 * @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
1062 * for further information.
1063 */
1064 template <int dim, int spacedim, typename number>
1065 void
1066 make_periodicity_constraints(const DoFHandler<dim, spacedim> &dof_handler,
1067 const types::boundary_id b_id,
1068 const unsigned int direction,
1069 AffineConstraints<number> &constraints,
1070 const ComponentMask &component_mask = {},
1071 const number periodicity_factor = 1.);
1072
1073 namespace internal
1074 {
1075 /**
1076 * This function is internally used in make_periodicity_constraints().
1077 * Enter constraints for periodicity into the given AffineConstraints
1078 * object.
1079 *
1080 * This function works both on 1) an active mesh
1081 * (`level == numbers::invalid_unsigned_int`) and on 2) multigrid levels.
1082 *
1083 * In the case of an active mesh, this function is called when at least
1084 * one of the two face iterators corresponds to an active object
1085 * without further children. Furthermore, @p face_1 is supposed to be active.
1086 *
1087 * The matrix @p transformation maps degrees of freedom from one face
1088 * to another. If the DoFs on the two faces are supposed to match exactly,
1089 * then the matrix so provided will be the identity matrix. if face 2 is
1090 * once refined from face 1, then the matrix needs to be the interpolation
1091 * matrix from a face to this particular child
1092 *
1093 * @note We have to be careful not to accidentally create constraint
1094 * cycles when adding periodic constraints: For example, as the
1095 * corresponding testcase bits/periodicity_05 demonstrates, we can
1096 * occasionally get into trouble if we already have the constraint
1097 * x1 == x2 and want to insert x2 == x1. We avoid this by skipping
1098 * such "identity constraints" if the opposite constraint already
1099 * exists.
1100 */
1101 template <typename FaceIterator, typename number>
1102 void
1103 set_periodicity_constraints(
1104 const FaceIterator &face_1,
1105 const std_cxx20::type_identity_t<FaceIterator> &face_2,
1106 const FullMatrix<double> &transformation,
1107 AffineConstraints<number> &affine_constraints,
1108 const ComponentMask &component_mask,
1109 const types::geometric_orientation combined_orientation,
1110 const number periodicity_factor,
1111 const unsigned int level = numbers::invalid_unsigned_int);
1112 } // namespace internal
1113
1114 /**
1115 * @}
1116 */
1117
1118 /**
1119 * @name Identifying subsets of degrees of freedom with particular properties
1120 * @{
1121 */
1122
1123 /**
1124 * Return an IndexSet describing all dofs that will be constrained by
1125 * interface constraints, i.e. all hanging nodes.
1126 *
1127 * In case of a parallel::shared::Triangulation or a
1128 * parallel::distributed::Triangulation only locally relevant dofs are
1129 * considered.
1130 */
1131 template <int dim, int spacedim>
1132 IndexSet
1133 extract_hanging_node_dofs(const DoFHandler<dim, spacedim> &dof_handler);
1134
1135 /**
1136 * Extract the (locally owned) indices of the degrees of freedom belonging to
1137 * certain vector components of a vector-valued finite element. The
1138 * @p component_mask defines which components or blocks of an FESystem or
1139 * vector-valued element are to be extracted
1140 * from the DoFHandler @p dof. The entries in the output object then
1141 * correspond to degrees of freedom belonging to these
1142 * components.
1143 *
1144 * If the finite element under consideration is not primitive, i.e., some or
1145 * all of its shape functions are non-zero in more than one vector component
1146 * (which holds, for example, for FE_Nedelec or FE_RaviartThomas elements),
1147 * then shape functions cannot be associated with a single vector component.
1148 * In this case, if <em>one</em> shape vector component of this element is
1149 * flagged in @p component_mask (see
1150 * @ref GlossComponentMask),
1151 * then this is equivalent to selecting <em>all</em> vector components
1152 * corresponding to this non-primitive base element.
1153 *
1154 * @param[in] dof_handler The DoFHandler whose enumerated degrees of freedom
1155 * are to be filtered by this function.
1156 * @param[in] component_mask A mask that states which components you want
1157 * to select. The size of this mask must be compatible with the number of
1158 * components in the FiniteElement used by the @p dof_handler. A common
1159 * way to create this kind of mask is using extractors for whatever
1160 * vector component you want to extract, and using it with
1161 * FiniteElement::component_mask(). See
1162 * @ref GlossComponentMask "the glossary entry on component masks"
1163 * for more information.
1164 * @return An IndexSet object that will contain exactly those entries that
1165 * (i) correspond to degrees of freedom selected by the mask above, and
1166 * (ii) are locally owned. The size of the index set is equal to the global
1167 * number of degrees of freedom. Note that the resulting object is always
1168 * a subset of what DoFHandler::locally_owned_dofs() returns.
1169 */
1170 template <int dim, int spacedim>
1171 IndexSet
1172 extract_dofs(const DoFHandler<dim, spacedim> &dof_handler,
1173 const ComponentMask &component_mask);
1174
1175 /**
1176 * This function is the equivalent to the DoFTools::extract_dofs() functions
1177 * above except that the selection of which degrees of freedom to extract is
1178 * not done based on components (see
1179 * @ref GlossComponent)
1180 * but instead based on whether they are part of a particular block (see
1181 * @ref GlossBlock).
1182 * Consequently, the second argument is not a ComponentMask but a BlockMask
1183 * object.
1184 *
1185 * @param[in] dof_handler The DoFHandler whose enumerated degrees of freedom
1186 * are to be filtered by this function.
1187 * @param[in] block_mask A mask that states which blocks you want
1188 * to select. The size of this mask must be compatible with the number of
1189 * blocks in the FiniteElement used by the @p dof_handler. See
1190 * @ref GlossBlockMask "the glossary entry on block masks"
1191 * for more information.
1192 * @return An IndexSet object that will contain exactly those entries that
1193 * (i) correspond to degrees of freedom selected by the mask above, and
1194 * (ii) are locally owned. The size of the index set is equal to the global
1195 * number of degrees of freedom. Note that the resulting object is always
1196 * a subset of what DoFHandler::locally_owned_dofs() returns.
1197 */
1198 template <int dim, int spacedim>
1199 IndexSet
1200 extract_dofs(const DoFHandler<dim, spacedim> &dof_handler,
1201 const BlockMask &block_mask);
1202
1203 /**
1204 * Do the same thing as the corresponding extract_dofs() function for one
1205 * level of a multi-grid DoF numbering.
1206 */
1207 template <int dim, int spacedim>
1208 void
1209 extract_level_dofs(const unsigned int level,
1210 const DoFHandler<dim, spacedim> &dof,
1211 const ComponentMask &component_mask,
1212 std::vector<bool> &selected_dofs);
1213
1214 /**
1215 * Do the same thing as the corresponding extract_dofs() function for one
1216 * level of a multi-grid DoF numbering.
1217 */
1218 template <int dim, int spacedim>
1219 void
1220 extract_level_dofs(const unsigned int level,
1221 const DoFHandler<dim, spacedim> &dof,
1222 const BlockMask &component_mask,
1223 std::vector<bool> &selected_dofs);
1224
1225 /**
1226 * Extract all degrees of freedom which are at the boundary and belong to
1227 * specified components of the solution. The function returns its results in
1228 * the form of an IndexSet that contains those entries that correspond to
1229 * these selected degrees of freedom, i.e., which are at the boundary and
1230 * belong to one of the selected components.
1231 *
1232 * By specifying the @p boundary_ids variable, you can select which boundary
1233 * indicators the faces have to have on which the degrees of freedom are
1234 * located that shall be extracted. If it is an empty list (the default), then
1235 * all boundary indicators are accepted.
1236 *
1237 * This function is used in step-11 and step-15, for example.
1238 *
1239 * @note If the DoFHandler object is defined on a
1240 * parallel Triangulation object, then the computed index set
1241 * will contain only those degrees of freedom on the boundary that belong to
1242 * the locally relevant set (see
1243 * @ref GlossLocallyRelevantDof "locally relevant DoFs"), i.e., the function
1244 * only considers faces of locally owned and ghost cells, but not of
1245 * artificial cells.
1246 *
1247 * @param[in] dof_handler The object that describes which degrees of freedom
1248 * live on which cell.
1249 * @param[in] component_mask A mask denoting the vector components of the
1250 * finite element that should be considered (see also
1251 * @ref GlossComponentMask). If left at the default, the component mask
1252 * indicates that all vector components of the finite element should be
1253 * considered.
1254 * @param[in] boundary_ids If empty, this function extracts the indices of the
1255 * degrees of freedom for all parts of the boundary. If it is a non-empty
1256 * list, then the function only considers boundary faces with the boundary
1257 * indicators listed in this argument.
1258 * @return The IndexSet object that
1259 * will contain the indices of degrees of freedom that are located on the
1260 * boundary (and correspond to the selected vector components and boundary
1261 * indicators, depending on the values of the @p component_mask and @p
1262 * boundary_ids arguments).
1263 *
1264 * @see
1265 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
1266 */
1267 template <int dim, int spacedim>
1268 IndexSet
1269 extract_boundary_dofs(const DoFHandler<dim, spacedim> &dof_handler,
1270 const ComponentMask &component_mask = {},
1271 const std::set<types::boundary_id> &boundary_ids = {});
1272
1273 /**
1274 * This function is similar to the extract_boundary_dofs() function but it
1275 * extracts those degrees of freedom whose shape functions are nonzero on at
1276 * least part of the selected boundary. For continuous elements, this is
1277 * exactly the set of shape functions whose degrees of freedom are defined
1278 * on boundary faces. On the other hand, if the finite element in used is a
1279 * discontinuous element, all degrees of freedom are defined in the inside
1280 * of cells and consequently none would be boundary degrees of freedom.
1281 * Several of those would have shape functions that are nonzero on the
1282 * boundary, however. This function therefore extracts all those for which
1283 * the FiniteElement::has_support_on_face function says that it is nonzero
1284 * on any face on one of the selected boundary parts.
1285 *
1286 * @see
1287 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
1288 */
1289 template <int dim, int spacedim>
1290 void
1291 extract_dofs_with_support_on_boundary(
1292 const DoFHandler<dim, spacedim> &dof_handler,
1293 const ComponentMask &component_mask,
1294 std::vector<bool> &selected_dofs,
1295 const std::set<types::boundary_id> &boundary_ids =
1296 std::set<types::boundary_id>());
1297
1298 /**
1299 * Extract all indices of shape functions such that their support is entirely
1300 * contained within the cells for which the @p predicate is <code>true</code>.
1301 * The result is returned as an IndexSet.
1302 *
1303 * Consider the following FE space where predicate returns <code>true</code>
1304 * for all cells on the left half of the domain:
1305 *
1306 * @image html extract_dofs_with_support_contained_within.png
1307 *
1308 * This functions will return the union of all DoF indices on those cells
1309 * minus DoF 11, 13, 2 and 0; the result will be <code>[9,10], 12,
1310 * [14,38]</code>. In the image above the returned DoFs are separated from the
1311 * rest by the red line
1312 *
1313 * Essentially, the question this functions answers is the following:
1314 * Given a subdomain with associated DoFs, what is the largest subset of
1315 * these DoFs that are allowed to be non-zero such that after calling
1316 * AffineConstraints::distribute() the resulting solution vector will have
1317 * support only within the given domain. Here, @p constraints is the
1318 * AffineConstraints container containing hanging nodes constraints.
1319 *
1320 * In case of parallel::distributed::Triangulation @p predicate will be called
1321 * only for locally owned and ghost cells. The resulting index set may contain
1322 * DoFs that are associated with the locally owned or ghost cells, but are not
1323 * owned by the current MPI core.
1324 */
1325 template <int dim, int spacedim, typename number = double>
1326 IndexSet
1327 extract_dofs_with_support_contained_within(
1328 const DoFHandler<dim, spacedim> &dof_handler,
1329 const std::function<
1330 bool(const typename DoFHandler<dim, spacedim>::active_cell_iterator &)>
1331 &predicate,
1332 const AffineConstraints<number> &constraints = {});
1333
1334 /**
1335 * Extract a vector that represents the constant modes of the DoFHandler for
1336 * the components chosen by <tt>component_mask</tt> (see
1337 * @ref GlossComponentMask).
1338 * The constant modes on a discretization are the null space of a Laplace
1339 * operator on the selected components with Neumann boundary conditions
1340 * applied. The null space is a necessary ingredient for obtaining a good
1341 * AMG preconditioner when using the class
1342 * TrilinosWrappers::PreconditionAMG. Since the ML AMG package only works
1343 * on algebraic properties of the respective matrix, it has no chance to
1344 * detect whether the matrix comes from a scalar or a vector valued problem.
1345 * However, a near null space supplies exactly the needed information about
1346 * the components' placement of vector components within the matrix. The null
1347 * space (or rather, the constant modes) is provided by the finite element
1348 * underlying the given DoFHandler and for most elements, the null space
1349 * will consist of as many vectors as there are `true` arguments in
1350 * <tt>component_mask</tt> (see
1351 * @ref GlossComponentMask),
1352 * each of which will be one in one vector component and zero in all others.
1353 * However, the representation of the constant function for e.g. FE_DGP is
1354 * different (the first component on each element one, all other components
1355 * zero), and some scalar elements may even have two constant modes
1356 * (FE_Q_DG0). Therefore, we store this object in a vector of vectors, where
1357 * the outer vector contains the collection of the actual constant modes on
1358 * the DoFHandler. Each inner vector has as many components as there are
1359 * (locally owned) degrees of freedom in the selected components. Note that
1360 * any matrix associated with this null space must have been constructed
1361 * using the same <tt>component_mask</tt> argument, since the numbering of
1362 * DoFs is done relative to the selected dofs, not to all dofs.
1363 *
1364 * The main reason for this program is the use of the null space with the
1365 * AMG preconditioner.
1366 *
1367 * This function is used in step-31, step-32, and step-42, for example.
1368 */
1369 template <int dim, int spacedim>
1370 std::vector<std::vector<bool>>
1371 extract_constant_modes(const DoFHandler<dim, spacedim> &dof_handler,
1372 const ComponentMask &component_mask = {});
1373
1374 /**
1375 * Same as above.
1376 *
1377 * @deprecated
1378 */
1379 template <int dim, int spacedim>
1380 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
1381 "Use the other function that returns the constant modes by value, rather than via an argument.")
1382 void extract_constant_modes(const DoFHandler<dim, spacedim> &dof_handler,
1383 const ComponentMask &component_mask,
1384 std::vector<std::vector<bool>> &constant_modes);
1385
1386 /**
1387 * Same as above but for multigrid levels.
1388 */
1389 template <int dim, int spacedim>
1390 std::vector<std::vector<bool>>
1391 extract_level_constant_modes(const unsigned int level,
1392 const DoFHandler<dim, spacedim> &dof_handler,
1393 const ComponentMask &component_mask = {});
1394
1395 /**
1396 * Same as above.
1397 *
1398 * @deprecated
1399 */
1400 template <int dim, int spacedim>
1401 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
1402 "Use the other function that returns the constant modes by value, rather than via an argument.")
1403 void extract_level_constant_modes(
1404 const unsigned int level,
1405 const DoFHandler<dim, spacedim> &dof_handler,
1406 const ComponentMask &component_mask,
1407 std::vector<std::vector<bool>> &constant_modes);
1408
1409 /**
1410 * Same as the above but additional to the translational modes also
1411 * the rotational modes are added, needed, e.g., to set up AMG for solving
1412 * elasticity problems.
1413 */
1414 template <int dim, int spacedim>
1415 std::vector<std::vector<double>>
1416 extract_rigid_body_modes(const Mapping<dim, spacedim> &mapping,
1417 const DoFHandler<dim, spacedim> &dof_handler,
1418 const ComponentMask &component_mask = {});
1419
1420 /**
1421 * Same as above but for multigrid levels.
1422 */
1423 template <int dim, int spacedim>
1424 std::vector<std::vector<double>>
1425 extract_level_rigid_body_modes(const unsigned int level,
1426 const Mapping<dim, spacedim> &mapping,
1427 const DoFHandler<dim, spacedim> &dof_handler,
1428 const ComponentMask &component_mask = {});
1429 /** @} */
1430
1431 /**
1432 * @name Coupling between DoFHandler objects on different dimensions
1433 * @{
1434 */
1435
1436 /**
1437 * This function generates a mapping of codimension-1 active DoFHandler cell
1438 * iterators to codimension-0 cells and face indices, for DoFHandler objects
1439 * built on top of the boundary of a given `Triangulation<spacedim>`.
1440 *
1441 * If you need to couple a PDE defined on the surface of an existing
1442 * Triangulation (as in step-38) with the PDE defined on the bulk (say, for
1443 * example, a hyper ball and its boundary), the information that is returned
1444 * by the function GridGenerator::extract_boundary_mesh() is not enough, since
1445 * you need to build FEValues objects on active cell iterators of the
1446 * DoFHandler defined on the surface mesh, and FEFaceValues objects on face
1447 * iterators of the DoFHandler defined on the bulk mesh. This second step
1448 * requires knowledge of the bulk cell iterator and of the corresponding face
1449 * index.
1450 *
1451 * This function examines the map `c1_to_c0` returned by
1452 * GridGenerator::extract_boundary_mesh() (when used with two Triangulation
1453 * objects as input), and associates to each active cell iterator of the
1454 * `c1_dh` DoFHandler that is also contained in the map `c1_to_c0`, a pair of
1455 * corresponding active bulk cell iterator of `c0_dh`, and face index
1456 * corresponding to the cell iterator on the surface mesh.
1457 *
1458 * An example usage of this function is the following:
1459 *
1460 * @code
1461 * Triangulation<dim> triangulation;
1462 * Triangulation<dim - 1, dim> surface_triangulation;
1463 *
1464 * FE_Q<dim> fe(1);
1465 * DoFHandler<dim> dof_handler(triangulation);
1466 *
1467 * FE_Q<dim - 1, dim> surface_fe(1);
1468 * DoFHandler<dim - 1, dim> surface_dof_handler(surface_triangulation);
1469 *
1470 * GridGenerator::half_hyper_ball(triangulation);
1471 * triangulation.refine_global(4);
1472 *
1473 * surface_triangulation.set_manifold(0, SphericalManifold<dim - 1, dim>());
1474 * const auto surface_to_bulk_map =
1475 * GridGenerator::extract_boundary_mesh(triangulation,
1476 * surface_triangulation,
1477 * {0});
1478 *
1479 * dof_handler.distribute_dofs(fe);
1480 * surface_dof_handler.distribute_dofs(surface_fe);
1481 *
1482 * // Extract the mapping between surface and bulk degrees of freedom:
1483 * const auto surface_to_bulk_dof_iterator_map =
1484 * DoFTools::map_boundary_to_bulk_dof_iterators(surface_to_bulk_map,
1485 * dof_handler,
1486 * surface_dof_handler);
1487 *
1488 * // Loop over the map, and print some information:
1489 * for (const auto &p : surface_to_bulk_dof_iterator_map)
1490 * {
1491 * const auto &surface_cell = p.first;
1492 * const auto &bulk_cell = p.second.first;
1493 * const auto &bulk_face = p.second.second;
1494 * deallog << "Surface cell " << surface_cell << " coincides with face "
1495 * << bulk_face << " of bulk cell " << bulk_cell << std::endl;
1496 * }
1497 * @endcode
1498 *
1499 * \tparam dim The dimension of the codimension-0 mesh.
1500 *
1501 * \tparam spacedim The dimension of the underlying space.
1502 *
1503 * \param[in] c1_to_c0 A map from codimension-1 triangulation cell iterators
1504 * to codimension-0 face iterators, as generated by the
1505 * GridGenerators::extract_boundary_mesh() function.
1506 *
1507 * \param[in] c0_dh The DoFHandler object of the codimension-0 mesh.
1508 *
1509 * \param[in] c1_dh The DoFHandler object of the codimension-1 mesh.
1510 *
1511 * \return A std::map object that maps codimension-1 active DoFHandler cell
1512 * iterators to a pair consisting of the corresponding codimension-0 cell
1513 * iterator and face index.
1514 */
1515 template <int dim, int spacedim>
1516 std::map<typename DoFHandler<dim - 1, spacedim>::active_cell_iterator,
1517 std::pair<typename DoFHandler<dim, spacedim>::active_cell_iterator,
1518 unsigned int>>
1519 map_boundary_to_bulk_dof_iterators(
1520 const std::map<typename Triangulation<dim - 1, spacedim>::cell_iterator,
1521 typename Triangulation<dim, spacedim>::face_iterator>
1522 &c1_to_c0,
1523 const DoFHandler<dim, spacedim> &c0_dh,
1524 const DoFHandler<dim - 1, spacedim> &c1_dh);
1525
1526 /**
1527 * @}
1528 */
1529
1530 /**
1531 * @name Parallelization and domain decomposition
1532 * @{
1533 */
1534 /**
1535 * Flag all those degrees of freedom which are on cells with the given
1536 * subdomain id. Note that DoFs on faces can belong to cells with differing
1537 * subdomain ids, so the sets of flagged degrees of freedom are not mutually
1538 * exclusive for different subdomain ids.
1539 *
1540 * If you want to get a unique association of degree of freedom with
1541 * subdomains, use the @p get_subdomain_association function.
1542 */
1543 template <int dim, int spacedim>
1544 void
1545 extract_subdomain_dofs(const DoFHandler<dim, spacedim> &dof_handler,
1546 const types::subdomain_id subdomain_id,
1547 std::vector<bool> &selected_dofs);
1548
1549 /**
1550 * Extract the set of global DoF indices that are active on the current
1551 * DoFHandler. For regular DoFHandlers, these are all DoF indices, but for
1552 * DoFHandler objects built on parallel::distributed::Triangulation this set
1553 * is a superset of DoFHandler::locally_owned_dofs() and contains all DoF
1554 * indices that live on all locally owned cells (including on the interface
1555 * to ghost cells). However, it does not contain the DoF indices that are
1556 * exclusively defined on ghost or artificial cells (see
1557 * @ref GlossArtificialCell "the glossary").
1558 *
1559 * The degrees of freedom identified by this function equal those obtained
1560 * from the dof_indices_with_subdomain_association() function when called
1561 * with the locally owned subdomain id.
1562 */
1563 template <int dim, int spacedim>
1564 IndexSet
1565 extract_locally_active_dofs(const DoFHandler<dim, spacedim> &dof_handler);
1566
1567 /**
1568 * Extract the set of global DoF indices that are active on the current
1569 * DoFHandler. For regular DoFHandlers, these are all DoF indices, but for
1570 * DoFHandler objects built on parallel::distributed::Triangulation this set
1571 * is a superset of DoFHandler::locally_owned_dofs() and contains all DoF
1572 * indices that live on all locally owned cells (including on the interface
1573 * to ghost cells). However, it does not contain the DoF indices that are
1574 * exclusively defined on ghost or artificial cells (see
1575 * @ref GlossArtificialCell "the glossary").
1576 *
1577 * The degrees of freedom identified by this function equal those obtained
1578 * from the dof_indices_with_subdomain_association() function when called
1579 * with the locally owned subdomain id.
1580 *
1581 * @deprecated Use the previous function instead.
1582 */
1583 template <int dim, int spacedim>
1584 DEAL_II_DEPRECATED void
1585 extract_locally_active_dofs(const DoFHandler<dim, spacedim> &dof_handler,
1586 IndexSet &dof_set);
1587
1588 /**
1589 * Same function as above but for a certain (multigrid-)level.
1590 * This function returns all DoF indices that live on
1591 * all locally owned cells (including on the interface to ghost cells) on the
1592 * given level.
1593 */
1594 template <int dim, int spacedim>
1595 IndexSet
1596 extract_locally_active_level_dofs(
1597 const DoFHandler<dim, spacedim> &dof_handler,
1598 const unsigned int level);
1599
1600 /**
1601 * Same function as above but for a certain (multigrid-)level.
1602 * This function returns all DoF indices that live on
1603 * all locally owned cells (including on the interface to ghost cells) on the
1604 * given level.
1605 *
1606 * @deprecated Use the previous function instead.
1607 */
1608 template <int dim, int spacedim>
1609 DEAL_II_DEPRECATED void
1610 extract_locally_active_level_dofs(
1611 const DoFHandler<dim, spacedim> &dof_handler,
1612 IndexSet &dof_set,
1613 const unsigned int level);
1614
1615 /**
1616 * Extract the set of global DoF indices that are active on the current
1617 * DoFHandler. For regular DoFHandlers, these are all DoF indices, but for
1618 * DoFHandler objects built on parallel::distributed::Triangulation this set
1619 * is the union of DoFHandler::locally_owned_dofs() and the DoF indices on
1620 * all ghost cells. In essence, it is the DoF indices on all cells that are
1621 * not artificial (see
1622 * @ref GlossArtificialCell "the glossary").
1623 */
1624 template <int dim, int spacedim>
1625 IndexSet
1626 extract_locally_relevant_dofs(const DoFHandler<dim, spacedim> &dof_handler);
1627
1628 /**
1629 * Extract the set of global DoF indices that are active on the current
1630 * DoFHandler. For regular DoFHandlers, these are all DoF indices, but for
1631 * DoFHandler objects built on parallel::distributed::Triangulation this set
1632 * is the union of DoFHandler::locally_owned_dofs() and the DoF indices on
1633 * all ghost cells. In essence, it is the DoF indices on all cells that are
1634 * not artificial (see @ref GlossArtificialCell "the glossary").
1635 *
1636 * @deprecated Use the previous function instead.
1637 */
1638 template <int dim, int spacedim>
1639 DEAL_II_DEPRECATED void
1640 extract_locally_relevant_dofs(const DoFHandler<dim, spacedim> &dof_handler,
1641 IndexSet &dof_set);
1642
1643 /**
1644 * Extract the set of locally owned DoF indices for each component within the
1645 * mask that are owned by the current processor. For components disabled by
1646 * the mask, an empty IndexSet is returned. For a scalar DoFHandler built on a
1647 * sequential triangulation, the return vector contains a single complete
1648 * IndexSet with all DoF indices. If the mask contains all components (which
1649 * also corresponds to the default value), then the union of the returned
1650 * index sets equals what DoFHandler::locally_owned_dofs() returns.
1651 */
1652 template <int dim, int spacedim>
1653 std::vector<IndexSet>
1654 locally_owned_dofs_per_component(const DoFHandler<dim, spacedim> &dof_handler,
1655 const ComponentMask &components = {});
1656
1657 /**
1658 * For each processor, determine the set of locally owned degrees of freedom
1659 * as an IndexSet. This function then returns a vector of index sets, where
1660 * the vector has size equal to the number of MPI processes that participate
1661 * in the DoF handler object.
1662 *
1663 * The function can be used for objects of type dealii::Triangulation or
1664 * parallel::shared::Triangulation. It will not work for objects of type
1665 * parallel::distributed::Triangulation since for such triangulations we do
1666 * not have information about all cells of the triangulation available
1667 * locally, and consequently can not say anything definitive about the
1668 * degrees of freedom active on other processors' locally owned cells.
1669 */
1670 template <int dim, int spacedim>
1671 std::vector<IndexSet>
1672 locally_owned_dofs_per_subdomain(
1673 const DoFHandler<dim, spacedim> &dof_handler);
1674
1675 /**
1676 *
1677 * For each processor, determine the set of locally relevant degrees of
1678 * freedom as an IndexSet. This function then returns a vector of index
1679 * sets, where the vector has size equal to the number of MPI processes that
1680 * participate in the DoF handler object.
1681 *
1682 * The function can be used for objects of type dealii::Triangulation or
1683 * parallel::shared::Triangulation. It will not work for objects of type
1684 * parallel::distributed::Triangulation since for such triangulations we do
1685 * not have information about all cells of the triangulation available
1686 * locally, and consequently can not say anything definitive about the
1687 * degrees of freedom active on other processors' locally owned cells.
1688 */
1689 template <int dim, int spacedim>
1690 std::vector<IndexSet>
1691 locally_relevant_dofs_per_subdomain(
1692 const DoFHandler<dim, spacedim> &dof_handler);
1693
1694 /**
1695 * Same as extract_locally_relevant_dofs() but for multigrid DoFs for the
1696 * given @p level.
1697 */
1698 template <int dim, int spacedim>
1699 IndexSet
1700 extract_locally_relevant_level_dofs(
1701 const DoFHandler<dim, spacedim> &dof_handler,
1702 const unsigned int level);
1703
1704 /**
1705 * Same as extract_locally_relevant_dofs() but for multigrid DoFs for the
1706 * given @p level.
1707 *
1708 * @deprecated Use the previous function instead.
1709 */
1710 template <int dim, int spacedim>
1711 DEAL_II_DEPRECATED void
1712 extract_locally_relevant_level_dofs(
1713 const DoFHandler<dim, spacedim> &dof_handler,
1714 const unsigned int level,
1715 IndexSet &dof_set);
1716
1717
1718 /**
1719 * For each degree of freedom, return in the output array to which subdomain
1720 * (as given by the <tt>cell->subdomain_id()</tt> function) it belongs. The
1721 * output array is supposed to have the right size already when calling this
1722 * function.
1723 *
1724 * Note that degrees of freedom associated with faces, edges, and vertices
1725 * may be associated with multiple subdomains if they are sitting on
1726 * partition boundaries. In these cases, we assign them to the process with
1727 * the smaller subdomain id. This may lead to different numbers of degrees
1728 * of freedom in partitions, even if the number of cells is perfectly
1729 * equidistributed. While this is regrettable, it is not a problem in
1730 * practice since the number of degrees of freedom on partition boundaries
1731 * is asymptotically vanishing as we refine the mesh as long as the number
1732 * of partitions is kept constant.
1733 *
1734 * This function returns the association of each DoF with one subdomain. If
1735 * you are looking for the association of each @em cell with a subdomain,
1736 * either query the <tt>cell->subdomain_id()</tt> function, or use the
1737 * <tt>GridTools::get_subdomain_association</tt> function.
1738 *
1739 * Note that this function is of questionable use for DoFHandler objects
1740 * built on parallel::distributed::Triangulation since in that case
1741 * ownership of individual degrees of freedom by MPI processes is controlled
1742 * by the DoF handler object, not based on some geometric algorithm in
1743 * conjunction with subdomain id. In particular, the degrees of freedom
1744 * identified by the functions in this namespace as associated with a
1745 * subdomain are not the same the DoFHandler class identifies as those it
1746 * owns.
1747 */
1748 template <int dim, int spacedim>
1749 void
1750 get_subdomain_association(const DoFHandler<dim, spacedim> &dof_handler,
1751 std::vector<types::subdomain_id> &subdomain);
1752
1753 /**
1754 * Count how many degrees of freedom are uniquely associated with the given
1755 * @p subdomain index.
1756 *
1757 * Note that there may be rare cases where cells with the given @p subdomain
1758 * index exist, but none of its degrees of freedom are actually associated
1759 * with it. In that case, the returned value will be zero.
1760 *
1761 * This function will generate an exception if there are no cells with the
1762 * given @p subdomain index.
1763 *
1764 * This function returns the number of DoFs associated with one subdomain.
1765 * If you are looking for the association of @em cells with this subdomain,
1766 * use the <tt>GridTools::count_cells_with_subdomain_association</tt>
1767 * function.
1768 *
1769 * Note that this function is of questionable use for DoFHandler objects
1770 * built on parallel::distributed::Triangulation since in that case
1771 * ownership of individual degrees of freedom by MPI processes is controlled
1772 * by the DoF handler object, not based on some geometric algorithm in
1773 * conjunction with subdomain id. In particular, the degrees of freedom
1774 * identified by the functions in this namespace as associated with a
1775 * subdomain are not the same the DoFHandler class identifies as those it
1776 * owns.
1777 */
1778 template <int dim, int spacedim>
1779 unsigned int
1780 count_dofs_with_subdomain_association(
1781 const DoFHandler<dim, spacedim> &dof_handler,
1782 const types::subdomain_id subdomain);
1783
1784 /**
1785 * Count how many degrees of freedom are uniquely associated with the given
1786 * @p subdomain index.
1787 *
1788 * This function does what the previous one does except that it splits the
1789 * result among the vector components of the finite element in use by the
1790 * DoFHandler object. The last argument (which must have a length equal to
1791 * the number of vector components) will therefore store how many degrees of
1792 * freedom of each vector component are associated with the given subdomain.
1793 *
1794 * Note that this function is of questionable use for DoFHandler objects
1795 * built on parallel::distributed::Triangulation since in that case
1796 * ownership of individual degrees of freedom by MPI processes is controlled
1797 * by the DoF handler object, not based on some geometric algorithm in
1798 * conjunction with subdomain id. In particular, the degrees of freedom
1799 * identified by the functions in this namespace as associated with a
1800 * subdomain are not the same the DoFHandler class identifies as those it
1801 * owns.
1802 */
1803 template <int dim, int spacedim>
1804 void
1805 count_dofs_with_subdomain_association(
1806 const DoFHandler<dim, spacedim> &dof_handler,
1807 const types::subdomain_id subdomain,
1808 std::vector<unsigned int> &n_dofs_on_subdomain);
1809
1810 /**
1811 * Return a set of indices that denotes the degrees of freedom that live on
1812 * the given subdomain, i.e. that are on cells owned by the current
1813 * processor. Note that this includes the ones that this subdomain "owns"
1814 * (i.e. the ones for which get_subdomain_association() returns a value
1815 * equal to the subdomain given here and that are selected by the
1816 * DoFHandler::locally_owned_dofs() function) but also all of those that sit
1817 * on the boundary between the given subdomain and other subdomain. In
1818 * essence, degrees of freedom that sit on boundaries between subdomain will
1819 * be in the index sets returned by this function for more than one
1820 * subdomain.
1821 *
1822 * Note that this function is of questionable use for DoFHandler objects
1823 * built on parallel::distributed::Triangulation since in that case
1824 * ownership of individual degrees of freedom by MPI processes is controlled
1825 * by the DoF handler object, not based on some geometric algorithm in
1826 * conjunction with subdomain id. In particular, the degrees of freedom
1827 * identified by the functions in this namespace as associated with a
1828 * subdomain are not the same the DoFHandler class identifies as those it
1829 * owns.
1830 */
1831 template <int dim, int spacedim>
1832 IndexSet
1833 dof_indices_with_subdomain_association(
1834 const DoFHandler<dim, spacedim> &dof_handler,
1835 const types::subdomain_id subdomain);
1836 /** @} */
1837
1838 /**
1839 * @name DoF indices on patches of cells
1840 *
1841 * Create structures containing a large set of degrees of freedom for small
1842 * patches of cells. The resulting objects can be used in RelaxationBlockSOR
1843 * and related classes to implement Schwarz preconditioners and smoothers,
1844 * where the subdomains consist of small numbers of cells only.
1845 */
1846 /** @{ */
1847
1848 /**
1849 * Return the set of degrees of freedom that live on a set of cells (i.e., a
1850 * patch) described by the argument.
1851 *
1852 * Patches are often used in defining error estimators that require the
1853 * solution of a local problem on the patch surrounding each of the cells of
1854 * the mesh. You can get a list of cells that form the patch around a given
1855 * cell using GridTools::get_patch_around_cell(). While
1856 * DoFTools::count_dofs_on_patch() can be used to determine the size of
1857 * these local problems, so that one can assemble the local system and then
1858 * solve it, it is still necessary to provide a mapping between the global
1859 * indices of the degrees of freedom that live on the patch and a local
1860 * enumeration. This function provides such a local enumeration by returning
1861 * the set of degrees of freedom that live on the patch.
1862 *
1863 * Since this set is returned in the form of a std::vector, one can also
1864 * think of it as a mapping
1865 * @code
1866 * i -> global_dof_index
1867 * @endcode
1868 * where <code>i</code> is an index into the returned vector (i.e., a the
1869 * <i>local</i> index of a degree of freedom on the patch) and
1870 * <code>global_dof_index</code> is the global index of a degree of freedom
1871 * located on the patch. The array returned has size equal to
1872 * DoFTools::count_dofs_on_patch().
1873 *
1874 * @note The array returned is sorted by global DoF index. Consequently, if
1875 * one considers the index into this array a local DoF index, then the local
1876 * system that results retains the block structure of the global system.
1877 *
1878 * @param patch A collection of cells within an object of type
1879 * DoFHandler<dim, spacedim>::active_cell_iterator
1880 *
1881 * @return A list of those global degrees of freedom located on the patch,
1882 * as defined above.
1883 *
1884 * @note In the context of a parallel distributed computation, it only makes
1885 * sense to call this function on patches around locally owned cells. This
1886 * is because the neighbors of locally owned cells are either locally owned
1887 * themselves, or ghost cells. For both, we know that these are in fact the
1888 * real cells of the complete, parallel triangulation. We can also query the
1889 * degrees of freedom on these. In other words, this function can only work
1890 * if all cells in the patch are either locally owned or ghost cells.
1891 */
1892 template <int dim, int spacedim>
1893 std::vector<types::global_dof_index>
1894 get_dofs_on_patch(
1895 const std::vector<typename DoFHandler<dim, spacedim>::active_cell_iterator>
1896 &patch);
1897
1898 /**
1899 * Creates a sparsity pattern, which lists
1900 * the degrees of freedom associated to each cell on the given
1901 * level. This pattern can be used in RelaxationBlock classes as
1902 * block list for additive and multiplicative Schwarz methods.
1903 *
1904 * The row index in this pattern is the cell index resulting from
1905 * standard iteration through a level of the Triangulation. For a
1906 * parallel::distributed::Triangulation, only locally owned cells
1907 * are entered.
1908 *
1909 * The sparsity pattern is resized in this function to contain as
1910 * many rows as there are locally owned cells on a given level, as
1911 * many columns as there are degrees of freedom on this level.
1912 *
1913 * <tt>selected_dofs</tt> is a vector indexed by the local degrees
1914 * of freedom on a cell. If it is used, only such dofs are entered
1915 * into the block list which are selected. This allows for instance
1916 * the exclusion of components or of dofs on the boundary.
1917 */
1918 template <int dim, int spacedim>
1919 void
1920 make_cell_patches(SparsityPattern &block_list,
1921 const DoFHandler<dim, spacedim> &dof_handler,
1922 const unsigned int level,
1923 const std::vector<bool> &selected_dofs = {},
1924 const types::global_dof_index offset = 0);
1925
1926 /**
1927 * Create an incidence matrix that for every vertex on a given level of a
1928 * multilevel DoFHandler flags which degrees of freedom are associated with
1929 * the adjacent cells. This data structure is a matrix with as many rows as
1930 * there are vertices on a given level, as many columns as there are degrees
1931 * of freedom on this level, and entries that are either true or false. This
1932 * data structure is conveniently represented by a SparsityPattern object.
1933 * The sparsity pattern may be empty when entering this function and will be
1934 * reinitialized to the correct size.
1935 *
1936 * The function has some boolean arguments (listed below) controlling
1937 * details of the generated patches. The default settings are those for
1938 * Arnold-Falk-Winther type smoothers for divergence and curl conforming
1939 * finite elements with essential boundary conditions. Other applications
1940 * are possible, in particular changing <tt>boundary_patches</tt> for
1941 * non-essential boundary conditions.
1942 *
1943 * This function returns the <tt>vertex_mapping</tt>,
1944 * that contains the mapping from the vertex indices to the block indices
1945 * of the <tt>block_list</tt>. For vertices that do not lead to a vertex
1946 * patch, the entry in <tt>vertex_mapping</tt> contains the value
1947 * <tt>invalid_unsigned_int</tt>. If <tt>invert_vertex_mapping</tt> is set to
1948 * <tt>true</tt>, then the <tt>vertex_mapping</tt> is inverted such that it
1949 * contains the mapping from the block indices to the corresponding vertex
1950 * indices.
1951 *
1952 * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
1953 * be stored.
1954 *
1955 * @arg <tt>dof_handler</tt>: the multilevel dof handler providing the
1956 * topology operated on.
1957 *
1958 * @arg <tt>interior_dofs_only</tt>: for each patch of cells around a
1959 * vertex, collect only the interior degrees of freedom of the patch and
1960 * disregard those on the boundary of the patch. This is for instance the
1961 * setting for smoothers of Arnold-Falk-Winther type.
1962 *
1963 * @arg <tt>boundary_patches</tt>: include patches around vertices at the
1964 * boundary of the domain. If not, only patches around interior vertices
1965 * will be generated.
1966 *
1967 * @arg <tt>level_boundary_patches</tt>: same for refinement edges towards
1968 * coarser cells.
1969 *
1970 * @arg <tt>single_cell_patches</tt>: if not true, patches containing a
1971 * single cell are eliminated.
1972 *
1973 * @arg <tt>invert_vertex_mapping</tt>: if true, then the return value
1974 * contains one vertex index for each block; if false, then the return value
1975 * contains one block index or <tt>invalid_unsigned_int</tt> for each vertex.
1976 */
1977 template <int dim, int spacedim>
1978 std::vector<unsigned int>
1979 make_vertex_patches(SparsityPattern &block_list,
1980 const DoFHandler<dim, spacedim> &dof_handler,
1981 const unsigned int level,
1982 const bool interior_dofs_only,
1983 const bool boundary_patches = false,
1984 const bool level_boundary_patches = false,
1985 const bool single_cell_patches = false,
1986 const bool invert_vertex_mapping = false);
1987
1988 /**
1989 * Same as above but allows boundary dofs on blocks to be excluded
1990 * individually.
1991 *
1992 * This is helpful if you want to use, for example, Taylor Hood elements as
1993 * it allows you to not include the boundary DoFs for the velocity block on
1994 * the patches while also letting you include the boundary DoFs for the
1995 * pressure block.
1996 *
1997 * For each patch of cells around a vertex, collect all of the interior
1998 * degrees of freedom of the patch and disregard those on the boundary of
1999 * the patch if the boolean value for the corresponding block in the
2000 * BlockMask of @p exclude_boundary_dofs is false.
2001 */
2002 template <int dim, int spacedim>
2003 std::vector<unsigned int>
2004 make_vertex_patches(SparsityPattern &block_list,
2005 const DoFHandler<dim, spacedim> &dof_handler,
2006 const unsigned int level,
2007 const BlockMask &exclude_boundary_dofs = BlockMask(),
2008 const bool boundary_patches = false,
2009 const bool level_boundary_patches = false,
2010 const bool single_cell_patches = false,
2011 const bool invert_vertex_mapping = false);
2012
2013 /**
2014 * Create an incidence matrix that for every cell on a given level of a
2015 * multilevel DoFHandler flags which degrees of freedom are associated with
2016 * children of this cell. This data structure is conveniently represented by
2017 * a SparsityPattern object.
2018 *
2019 * The function thus creates a sparsity pattern which in each row (with rows
2020 * corresponding to the cells on this level) lists the degrees of freedom
2021 * associated to the cells that are the children of this cell. The DoF
2022 * indices used here are level dof indices of a multilevel hierarchy, i.e.,
2023 * they may be associated with children that are not themselves active. The
2024 * sparsity pattern may be empty when entering this function and will be
2025 * reinitialized to the correct size.
2026 *
2027 * The function has some boolean arguments (listed below) controlling
2028 * details of the generated patches. The default settings are those for
2029 * Arnold-Falk-Winther type smoothers for divergence and curl conforming
2030 * finite elements with essential boundary conditions. Other applications
2031 * are possible, in particular changing <tt>boundary_dofs</tt> for
2032 * non-essential boundary conditions.
2033 *
2034 * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
2035 * be stored.
2036 *
2037 * @arg <tt>dof_handler</tt>: The multilevel dof handler providing the
2038 * topology operated on.
2039 *
2040 * @arg <tt>interior_dofs_only</tt>: for each patch of cells around a
2041 * vertex, collect only the interior degrees of freedom of the patch and
2042 * disregard those on the boundary of the patch. This is for instance the
2043 * setting for smoothers of Arnold-Falk-Winther type.
2044 *
2045 * @arg <tt>boundary_dofs</tt>: include degrees of freedom, which would have
2046 * excluded by <tt>interior_dofs_only</tt>, but are lying on the boundary of
2047 * the domain, and thus need smoothing. This parameter has no effect if
2048 * <tt>interior_dofs_only</tt> is false.
2049 */
2050 template <int dim, int spacedim>
2051 void
2052 make_child_patches(SparsityPattern &block_list,
2053 const DoFHandler<dim, spacedim> &dof_handler,
2054 const unsigned int level,
2055 const bool interior_dofs_only,
2056 const bool boundary_dofs = false);
2057
2058 /**
2059 * Create a block list with only a single patch, which in turn contains all
2060 * degrees of freedom on the given level.
2061 *
2062 * This function is mostly a closure on level 0 for functions like
2063 * make_child_patches() and make_vertex_patches(), which may produce an
2064 * empty patch list.
2065 *
2066 * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
2067 * be stored.
2068 *
2069 * @arg <tt>dof_handler</tt>: The multilevel dof handler providing the
2070 * topology operated on.
2071 *
2072 * @arg <tt>level</tt> The grid level used for building the list.
2073 *
2074 * @arg <tt>interior_dofs_only</tt>: if true, exclude degrees of freedom on
2075 * the boundary of the domain.
2076 */
2077 template <int dim, int spacedim>
2078 void
2079 make_single_patch(SparsityPattern &block_list,
2080 const DoFHandler<dim, spacedim> &dof_handler,
2081 const unsigned int level,
2082 const bool interior_dofs_only = false);
2083
2084 /**
2085 * @}
2086 */
2087 /**
2088 * @name Counting degrees of freedom and related functions
2089 * @{
2090 */
2091
2092 /**
2093 * Count how many degrees of freedom out of the total number belong to each
2094 * component. If the number of components the finite element has is one
2095 * (i.e. you only have one scalar variable), then the number in this
2096 * component obviously equals the total number of degrees of freedom.
2097 * Otherwise, the sum of the DoFs in all the components needs to equal the
2098 * total number.
2099 *
2100 * However, the last statement does not hold true if the finite element is
2101 * not primitive, i.e. some or all of its shape functions are non-zero in
2102 * more than one vector component. This applies, for example, to the Nedelec
2103 * or Raviart-Thomas elements. In this case, a degree of freedom is counted
2104 * in each component in which it is non-zero, so that the sum mentioned
2105 * above is greater than the total number of degrees of freedom.
2106 *
2107 * This behavior can be switched off by the optional parameter
2108 * <tt>vector_valued_once</tt>. If this is <tt>true</tt>, the number of
2109 * components of a nonprimitive vector valued element is collected only in
2110 * the first component. All other components will have a count of zero.
2111 *
2112 * The additional optional argument @p target_component allows for a
2113 * re-sorting and grouping of components. To this end, it contains for each
2114 * component the component number it shall be counted as. Having the same
2115 * number entered several times sums up several components as the same. One
2116 * of the applications of this argument is when you want to form block
2117 * matrices and vectors, but want to pack several components into the same
2118 * block (for example, when you have @p dim velocities and one pressure, to
2119 * put all velocities into one block, and the pressure into another).
2120 *
2121 * The result is returned in @p dofs_per_component. Note that the size of @p
2122 * dofs_per_component needs to be enough to hold all the indices specified
2123 * in @p target_component. If this is not the case, an assertion is thrown.
2124 * The indices not targeted by target_components are left untouched.
2125 */
2126 template <int dim, int spacedim>
2127 std::vector<types::global_dof_index>
2128 count_dofs_per_fe_component(
2129 const DoFHandler<dim, spacedim> &dof_handler,
2130 const bool vector_valued_once = false,
2131 const std::vector<unsigned int> &target_component = {});
2132
2133 /**
2134 * Count the degrees of freedom in each block. This function is similar to
2135 * count_dofs_per_component(), with the difference that the counting is done
2136 * by blocks. See
2137 * @ref GlossBlock "blocks"
2138 * in the glossary for details. Again the vectors are assumed to have the
2139 * correct size before calling this function. If this is not the case, an
2140 * assertion is thrown.
2141 *
2142 * This function is used in the step-22, step-31, and step-32 tutorial
2143 * programs, among others.
2144 *
2145 * @pre The dofs_per_block variable has as many components as the finite
2146 * element used by the dof_handler argument has blocks, or alternatively as
2147 * many blocks as are enumerated in the target_blocks argument if given.
2148 */
2149 template <int dim, int spacedim>
2150 std::vector<types::global_dof_index>
2151 count_dofs_per_fe_block(const DoFHandler<dim, spacedim> &dof,
2152 const std::vector<unsigned int> &target_block =
2153 std::vector<unsigned int>());
2154
2155 /**
2156 * For each active cell of a DoFHandler, extract the active finite element
2157 * index and fill the vector given as second argument. This vector is assumed
2158 * to have as many entries as there are active cells.
2159 *
2160 * For DoFHandler objects without hp-capabilities given as first argument, the
2161 * returned vector will consist of only zeros, indicating that all cells use
2162 * the same finite element. In hp-mode, the values may be different, though.
2163 *
2164 * As we do not know the active FE index on artificial cells, we set them to
2165 * the invalid value numbers::invalid_fe_index.
2166 *
2167 * @deprecated Use DoFHandler::get_active_fe_indices() that returns the result
2168 * vector.
2169 */
2170 template <int dim, int spacedim>
2171 DEAL_II_DEPRECATED void
2172 get_active_fe_indices(const DoFHandler<dim, spacedim> &dof_handler,
2173 std::vector<unsigned int> &active_fe_indices);
2174
2175 /**
2176 * Count how many degrees of freedom live on a set of cells (i.e., a patch)
2177 * described by the argument.
2178 *
2179 * Patches are often used in defining error estimators that require the
2180 * solution of a local problem on the patch surrounding each of the cells of
2181 * the mesh. You can get a list of cells that form the patch around a given
2182 * cell using GridTools::get_patch_around_cell(). This function is then
2183 * useful in setting up the size of the linear system used to solve the
2184 * local problem on the patch around a cell. The function
2185 * DoFTools::get_dofs_on_patch() will then help to make the connection
2186 * between global degrees of freedom and the local ones.
2187 *
2188 * @param patch A collection of cells within an object of type
2189 * DoFHandler<dim, spacedim>
2190 *
2191 * @return The number of degrees of freedom associated with the cells of
2192 * this patch.
2193 *
2194 * @note In the context of a parallel distributed computation, it only makes
2195 * sense to call this function on patches around locally owned cells. This
2196 * is because the neighbors of locally owned cells are either locally owned
2197 * themselves, or ghost cells. For both, we know that these are in fact the
2198 * real cells of the complete, parallel triangulation. We can also query the
2199 * degrees of freedom on these. In other words, this function can only work
2200 * if all cells in the patch are either locally owned or ghost cells.
2201 */
2202 template <int dim, int spacedim>
2203 unsigned int
2204 count_dofs_on_patch(
2205 const std::vector<typename DoFHandler<dim, spacedim>::active_cell_iterator>
2206 &patch);
2207
2208 /**
2209 * @}
2210 */
2211
2212 /**
2213 * @name Functions that return different DoF mappings
2214 * @{
2215 */
2216
2217 /**
2218 * Create a mapping from degree of freedom indices to the index of that
2219 * degree of freedom on the boundary. After this operation,
2220 * <tt>mapping[dof]</tt> gives the index of the degree of freedom with
2221 * global number @p dof in the list of degrees of freedom on the boundary.
2222 * If the degree of freedom requested is not on the boundary, the value of
2223 * <tt>mapping[dof]</tt> is numbers::invalid_dof_index. This function is
2224 * mainly used when setting up matrices and vectors on the boundary from the
2225 * trial functions, which have global numbers, while the matrices and vectors
2226 * use numbers of the trial functions local to the boundary.
2227 *
2228 * Prior content of @p mapping is deleted.
2229 */
2230 template <int dim, int spacedim>
2231 void
2232 map_dof_to_boundary_indices(const DoFHandler<dim, spacedim> &dof_handler,
2233 std::vector<types::global_dof_index> &mapping);
2234
2235 /**
2236 * Same as the previous function, except that only those parts of the
2237 * boundary are considered for which the boundary indicator is listed in the
2238 * second argument.
2239 *
2240 * See the general doc of this class for more information.
2241 *
2242 * @see
2243 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
2244 */
2245 template <int dim, int spacedim>
2246 void
2247 map_dof_to_boundary_indices(const DoFHandler<dim, spacedim> &dof_handler,
2248 const std::set<types::boundary_id> &boundary_ids,
2249 std::vector<types::global_dof_index> &mapping);
2250
2251 /**
2252 * Return a list of support points (see this
2253 * @ref GlossSupport "glossary entry")
2254 * for all the degrees of freedom handled by this DoF handler object. This
2255 * function, of course, only works if the finite element object used by the
2256 * DoF handler object actually provides support points; this rules out
2257 * "modal" elements in which the shape functions are not defined via point
2258 * evaluation at individual node points, but by integrals. In practice, this
2259 * function checks the requirement by requiring that the element in question
2260 * returns `true` from the FiniteElement::has_support_points().
2261 *
2262 * @pre The given array `support_points` must have a length of as many
2263 * elements as there are degrees of freedom.
2264 *
2265 * @note The precondition to this function that the output argument needs to
2266 * have size equal to the total number of degrees of freedom makes this
2267 * function unsuitable for the case that the given DoFHandler object derives
2268 * from a parallel::TriangulationBase object (or any of the classes derived
2269 * from parallel::TriangulationBase). Consequently, this function will produce
2270 * an error if called with such a DoFHandler.
2271 *
2272 * @param[in] mapping The mapping from the reference cell to the real cell on
2273 * which DoFs are defined.
2274 * @param[in] dof_handler The object that describes which DoF indices live on
2275 * which cell of the triangulation.
2276 * @param[in,out] support_points A vector that stores the corresponding
2277 * location of the dofs in real space coordinates. Previous content of this
2278 * object is deleted in this function.
2279 * @param[in] mask An optional component mask that restricts the
2280 * components from which the support points are extracted.
2281 */
2282 template <int dim, int spacedim>
2283 void
2284 map_dofs_to_support_points(const Mapping<dim, spacedim> &mapping,
2285 const DoFHandler<dim, spacedim> &dof_handler,
2286 std::vector<Point<spacedim>> &support_points,
2287 const ComponentMask &mask = {});
2288
2289 /**
2290 * Same as the previous function but for the hp-case.
2291 */
2292 template <int dim, int spacedim>
2293 void
2294 map_dofs_to_support_points(
2295 const hp::MappingCollection<dim, spacedim> &mapping,
2296 const DoFHandler<dim, spacedim> &dof_handler,
2297 std::vector<Point<spacedim>> &support_points,
2298 const ComponentMask &mask = {});
2299
2300 /**
2301 * This function is a version of the above map_dofs_to_support_points
2302 * function that doesn't simply return a vector of support points (see this
2303 * @ref GlossSupport "glossary entry")
2304 * with one entry for each global degree of freedom, but instead a map that
2305 * maps from the DoFs index to its location. The point of this function is
2306 * that it is also usable in cases where the DoFHandler is based on a
2307 * parallel::TriangulationBase object (or any of the classes derived from
2308 * parallel::TriangulationBase). In such cases, each
2309 * processor will not be able to determine the support point location of all
2310 * DoFs, and worse no processor may be able to hold a vector that would
2311 * contain the locations of all DoFs even if they were known. As a
2312 * consequence, this function constructs a map from those DoFs for which we
2313 * can know the locations (namely, those DoFs that are locally relevant (see
2314 * @ref GlossLocallyRelevantDof "locally relevant DoFs")
2315 * to their locations.
2316 *
2317 * For non-distributed triangulations, the map returned as @p support_points
2318 * is of course dense, i.e., every DoF is to be found in it.
2319 *
2320 * @param[in] mapping The mapping from the reference cell to the real cell on
2321 * which DoFs are defined.
2322 * @param[in] dof_handler The object that describes which DoF indices live on
2323 * which cell of the triangulation.
2324 * @param[in] mask An optional component mask that restricts the
2325 * components from which the support points are extracted.
2326 * @return A map that for every locally relevant DoF
2327 * index contains the corresponding location in real space coordinates.
2328 */
2329 template <int dim, int spacedim>
2330 std::map<types::global_dof_index, Point<spacedim>>
2331 map_dofs_to_support_points(const Mapping<dim, spacedim> &mapping,
2332 const DoFHandler<dim, spacedim> &dof_handler,
2333 const ComponentMask &mask = {});
2334
2335 /**
2336 * Same as the previous function but for the hp-case.
2337 */
2338 template <int dim, int spacedim>
2339 std::map<types::global_dof_index, Point<spacedim>>
2340 map_dofs_to_support_points(
2341 const hp::MappingCollection<dim, spacedim> &mapping,
2342 const DoFHandler<dim, spacedim> &dof_handler,
2343 const ComponentMask &mask = {});
2344
2345 /**
2346 * A version of the function of same name that returns the map via its third
2347 * argument. This function is deprecated.
2348 * @deprecated Use the function that returns the `std::map` instead.
2349 */
2350 template <int dim, int spacedim>
2351 DEAL_II_DEPRECATED void
2352 map_dofs_to_support_points(
2353 const Mapping<dim, spacedim> &mapping,
2354 const DoFHandler<dim, spacedim> &dof_handler,
2355 std::map<types::global_dof_index, Point<spacedim>> &support_points,
2356 const ComponentMask &mask = {});
2357
2358 /**
2359 * A version of the function of same name that returns the map via its third
2360 * argument. This function is deprecated.
2361 * @deprecated Use the function that returns the `std::map` instead.
2362 */
2363 template <int dim, int spacedim>
2364 DEAL_II_DEPRECATED void
2365 map_dofs_to_support_points(
2366 const hp::MappingCollection<dim, spacedim> &mapping,
2367 const DoFHandler<dim, spacedim> &dof_handler,
2368 std::map<types::global_dof_index, Point<spacedim>> &support_points,
2369 const ComponentMask &mask = {});
2370
2371
2372 /**
2373 * This is the opposite function to the one above. It generates a map where
2374 * the keys are the support points of the degrees of freedom, while the
2375 * values are the DoF indices. For a definition of support points, see this
2376 * @ref GlossSupport "glossary entry".
2377 *
2378 * Since there is no natural order in the space of points (except for the 1d
2379 * case), you have to provide a map with an explicitly specified comparator
2380 * object. This function is therefore templatized on the comparator object.
2381 * Previous content of the map object is deleted in this function.
2382 *
2383 * Just as with the function above, it is assumed that the finite element in
2384 * use here actually supports the notion of support points of all its
2385 * components.
2386 *
2387 * @todo This function should generate a multimap, rather than just a map,
2388 * since several dofs may be located at the same support point. Currently,
2389 * only the last value in the map returned by map_dofs_to_support_points() for
2390 * each point will be returned.
2391 */
2392 template <int dim, int spacedim, class Comp>
2393 void
2394 map_support_points_to_dofs(
2395 const Mapping<dim, spacedim> &mapping,
2396 const DoFHandler<dim, spacedim> &dof_handler,
2397 std::map<Point<spacedim>, types::global_dof_index, Comp>
2398 &point_to_index_map);
2399 /**
2400 * @}
2401 */
2402
2403 /**
2404 * @name Miscellaneous
2405 * @{
2406 */
2407
2408 /**
2409 * Take a vector of values which live on cells (e.g. an error per cell) and
2410 * distribute it to the dofs in such a way that a finite element field
2411 * results, which can then be further processed, e.g. for output. You should
2412 * note that the resulting field will not be continuous at hanging nodes.
2413 * This can, however, easily be arranged by calling the appropriate @p
2414 * distribute function of an AffineConstraints object created for this
2415 * DoFHandler object, after the vector has been fully assembled.
2416 *
2417 * It is assumed that the number of elements in @p cell_data equals the
2418 * number of active cells and that the number of elements in @p dof_data
2419 * equals <tt>dof_handler.n_dofs()</tt>.
2420 *
2421 * Note that the input vector may be a vector of any data type as long as it
2422 * is convertible to @p double. The output vector, being a data vector on a
2423 * DoF handler, always consists of elements of type @p double.
2424 *
2425 * In case the finite element used by this DoFHandler consists of more than
2426 * one component, you need to specify which component in the output vector
2427 * should be used to store the finite element field in; the default is zero
2428 * (no other value is allowed if the finite element consists only of one
2429 * component). All other components of the vector remain untouched, i.e.
2430 * their contents are not changed.
2431 *
2432 * This function cannot be used if the finite element in use has shape
2433 * functions that are non-zero in more than one vector component (in deal.II
2434 * speak: they are non-primitive).
2435 */
2436 template <int dim, int spacedim, typename Number>
2437 void
2438 distribute_cell_to_dof_vector(const DoFHandler<dim, spacedim> &dof_handler,
2439 const Vector<Number> &cell_data,
2440 Vector<double> &dof_data,
2441 const unsigned int component = 0);
2442
2443
2444 /**
2445 * Generate text output readable by gnuplot with point data based on the
2446 * given map @p support_points. For each support point location, a string
2447 * label containing a list of all DoFs from the map is generated. The map
2448 * can be generated with a call to map_dofs_to_support_points() and is useful
2449 * to visualize location and global numbering of unknowns. This function is
2450 * used in step-2.
2451 *
2452 * An example for the format of each line in the output is:
2453 * @code
2454 * x [y] [z] "dof1, dof2"
2455 * @endcode
2456 * where x, y, and z (present only in corresponding dimension) are the
2457 * coordinates of the support point, followed by a list of DoF numbers.
2458 *
2459 * The points with labels can be plotted as follows in gnuplot:
2460 * @code
2461 * plot "./points.gpl" using 1:2:3 with labels point offset 1,1
2462 * @endcode
2463 *
2464 * Examples (this also includes the grid written separately using GridOut):
2465 * <p ALIGN="center">
2466 * @image html support_point_dofs1.png
2467 * @image html support_point_dofs2.png
2468 * </p>
2469 *
2470 * To generate the mesh and the support point information in a
2471 * single gnuplot file, use code similar to
2472 * @code
2473 * std::ofstream out("gnuplot.gpl");
2474 * out << "plot '-' using 1:2 with lines, "
2475 * << "'-' with labels point pt 2 offset 1,1"
2476 * << std::endl;
2477 * GridOut().write_gnuplot (triangulation, out);
2478 * out << 'e' << std::endl;
2479 *
2480 * std::map<types::global_dof_index, Point<dim> > support_points;
2481 * DoFTools::map_dofs_to_support_points (MappingQ1<dim>(),
2482 * dof_handler,
2483 * support_points);
2484 * DoFTools::write_gnuplot_dof_support_point_info(out,
2485 * support_points);
2486 * out << 'e' << std::endl;
2487 * @endcode
2488 * and from within gnuplot execute the following command:
2489 * @code
2490 * load "gnuplot.gpl"
2491 * @endcode
2492 *
2493 * Alternatively, the following gnuplot script will generate a png file when
2494 * executed as <tt>gnuplot gnuplot.gpl</tt> on the command line:
2495 * @code
2496 * std::ofstream out("gnuplot.gpl");
2497 *
2498 * out << "set terminal png size 400,410 enhanced font \"Helvetica,8\"\n"
2499 * << "set output \"output.png\"\n"
2500 * << "set size square\n"
2501 * << "set view equal xy\n"
2502 * << "unset xtics\n"
2503 * << "unset ytics\n"
2504 * << "unset grid\n"
2505 * << "unset border\n"
2506 * << "plot '-' using 1:2 with lines notitle, "
2507 * << "'-' with labels point pt 2 offset 1,1 notitle"
2508 * << std::endl;
2509 * GridOut().write_gnuplot (triangulation, out);
2510 * out << 'e' << std::endl;
2511 *
2512 * std::map<types::global_dof_index, Point<dim> > support_points;
2513 * DoFTools::map_dofs_to_support_points (MappingQ1<dim>(),
2514 * dof_handler,
2515 * support_points);
2516 * DoFTools::write_gnuplot_dof_support_point_info(out,
2517 * support_points);
2518 * out << 'e' << std::endl;
2519 * @endcode
2520 */
2521 template <int spacedim>
2522 void
2523 write_gnuplot_dof_support_point_info(
2524 std::ostream &out,
2525 const std::map<types::global_dof_index, Point<spacedim>> &support_points);
2526
2527
2528 /**
2529 * Add constraints to @p zero_boundary_constraints corresponding to
2530 * enforcing a zero boundary condition on the given boundary indicator.
2531 *
2532 * This function constrains all degrees of freedom on the given part of the
2533 * boundary.
2534 *
2535 * A variant of this function with different arguments is used in step-36.
2536 *
2537 * @param dof The DoFHandler to work on.
2538 * @param boundary_id The indicator of that part of the boundary for which
2539 * constraints should be computed. If this number equals
2540 * numbers::invalid_boundary_id then all boundaries of the domain will be
2541 * treated.
2542 * @param zero_boundary_constraints The constraint object into which the
2543 * constraints will be written. The new constraints due to zero boundary
2544 * values will simply be added, preserving any other constraints previously
2545 * present. However, this will only work if the previous content of that
2546 * object consists of constraints on degrees of freedom that are not located
2547 * on the boundary treated here. If there are previously existing
2548 * constraints for degrees of freedom located on the boundary, then this
2549 * would constitute a conflict. See the
2550 * @ref constraints
2551 * topic for handling the case where there are conflicting constraints on
2552 * individual degrees of freedom.
2553 * @param component_mask An optional component mask that restricts the
2554 * functionality of this function to a subset of an FESystem. For
2555 * non-@ref GlossPrimitive "primitive"
2556 * shape functions, any degree of freedom is affected that belongs to a
2557 * shape function where at least one of its nonzero components is affected
2558 * by the component mask (see
2559 * @ref GlossComponentMask).
2560 * If this argument is omitted, all components of the finite element with
2561 * degrees of freedom at the boundary will be considered.
2562 *
2563 * @ingroup constraints
2564 *
2565 * @see
2566 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
2567 */
2568 template <int dim, int spacedim, typename number>
2569 void
2570 make_zero_boundary_constraints(
2571 const DoFHandler<dim, spacedim> &dof,
2572 const types::boundary_id boundary_id,
2573 AffineConstraints<number> &zero_boundary_constraints,
2574 const ComponentMask &component_mask = {});
2575
2576 /**
2577 * Do the same as the previous function, except do it for all parts of the
2578 * boundary, not just those with a particular boundary indicator. This
2579 * function is then equivalent to calling the previous one with
2580 * numbers::invalid_boundary_id as second argument.
2581 *
2582 * This function is used in step-36, for example.
2583 *
2584 * @ingroup constraints
2585 */
2586 template <int dim, int spacedim, typename number>
2587 void
2588 make_zero_boundary_constraints(
2589 const DoFHandler<dim, spacedim> &dof,
2590 AffineConstraints<number> &zero_boundary_constraints,
2591 const ComponentMask &component_mask = {});
2592
2593 /**
2594 * @}
2595 */
2596
2597 /**
2598 * @name Exceptions
2599 * @{
2600 */
2601
2602 /**
2603 * @todo Write description
2604 *
2605 * @ingroup Exceptions
2606 */
2607 DeclException0(ExcFiniteElementsDontMatch);
2608 /**
2609 * @todo Write description
2610 *
2611 * @ingroup Exceptions
2612 */
2613 DeclException0(ExcGridNotCoarser);
2614 /**
2615 * @todo Write description
2616 *
2617 * Exception
2618 * @ingroup Exceptions
2619 */
2620 DeclException0(ExcGridsDontMatch);
2621 /**
2622 * The DoFHandler was not initialized with a finite element. Please call
2623 * DoFHandler::distribute_dofs() first.
2624 *
2625 * @ingroup Exceptions
2626 */
2627 DeclException0(ExcNoFESelected);
2628 /**
2629 * @todo Write description
2630 *
2631 * @ingroup Exceptions
2632 */
2633 DeclException0(ExcInvalidBoundaryIndicator);
2634 /**
2635 * @}
2636 */
2637 } // namespace DoFTools
2638
2639
2640
2641 /* ------------------------- inline functions -------------- */
2642
2643 #ifndef DOXYGEN
2644
2645 namespace DoFTools
2646 {
2647 /**
2648 * Operator computing the maximum coupling out of two.
2649 *
2650 * @relatesalso DoFTools
2651 */
2652 inline Coupling
2653 operator|=(Coupling &c1, const Coupling c2)
2654 {
2655 if (c2 == always)
2656 c1 = always;
2657 else if (c1 != always && c2 == nonzero)
2658 return c1 = nonzero;
2659 return c1;
2660 }
2661
2662
2663 /**
2664 * Operator computing the maximum coupling out of two.
2665 *
2666 * @relatesalso DoFTools
2667 */
2668 inline Coupling
2669 operator|(const Coupling c1, const Coupling c2)
2670 {
2671 if (c1 == always || c2 == always)
2672 return always;
2673 if (c1 == nonzero || c2 == nonzero)
2674 return nonzero;
2675 return none;
2676 }
2677
2678
2679 // ---------------------- inline and template functions --------------------
2680
2681 template <int dim, int spacedim, class Comp>
2682 void
2683 map_support_points_to_dofs(
2684 const Mapping<dim, spacedim> &mapping,
2685 const DoFHandler<dim, spacedim> &dof_handler,
2686 std::map<Point<spacedim>, types::global_dof_index, Comp>
2687 &point_to_index_map)
2688 {
2689 // let the checking of arguments be
2690 // done by the function first
2691 // called
2692 std::vector<Point<spacedim>> support_points(dof_handler.n_dofs());
2693 map_dofs_to_support_points(mapping, dof_handler, support_points);
2694 // now copy over the results of the
2695 // previous function into the
2696 // output arg
2697 point_to_index_map.clear();
2698 for (types::global_dof_index i = 0; i < dof_handler.n_dofs(); ++i)
2699 point_to_index_map[support_points[i]] = i;
2700 }
2701 } // namespace DoFTools
2702
2703 #endif
2704
2705 DEAL_II_NAMESPACE_CLOSE
2706
2707 #endif