Debian Codegraph @

include/deal.II/dofs/dof_handler.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 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_handler_h
16 #define dealii_dof_handler_h
17
18
19
20 #include <deal.II/base/config.h>
21
22 #include <deal.II/base/exceptions.h>
23 #include <deal.II/base/function.h>
24 #include <deal.II/base/index_set.h>
25 #include <deal.II/base/iterator_range.h>
26 #include <deal.II/base/observer_pointer.h>
27 #include <deal.II/base/types.h>
28
29 #include <deal.II/dofs/block_info.h>
30 #include <deal.II/dofs/dof_accessor.h>
31 #include <deal.II/dofs/dof_faces.h>
32 #include <deal.II/dofs/dof_iterator_selector.h>
33 #include <deal.II/dofs/dof_levels.h>
34 #include <deal.II/dofs/number_cache.h>
35
36 #include <deal.II/hp/fe_collection.h>
37
38 #include <boost/serialization/split_member.hpp>
39 #include <boost/signals2/connection.hpp>
40
41 #include <map>
42 #include <memory>
43 #include <set>
44 #include <vector>
45
46 DEAL_II_NAMESPACE_OPEN
47
48 // Forward declarations
49 #ifndef DOXYGEN
50 template <int dim, int spacedim>
51 class FiniteElement;
52 template <int dim, int spacedim>
53 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
54 class Triangulation;
55
56 namespace internal
57 {
58 namespace DoFHandlerImplementation
59 {
60 struct Implementation;
61
62 namespace Policy
63 {
64 template <int dim, int spacedim>
65 class PolicyBase;
66 struct Implementation;
67 } // namespace Policy
68 } // namespace DoFHandlerImplementation
69
70 namespace DoFAccessorImplementation
71 {
72 struct Implementation;
73 }
74
75 namespace DoFCellAccessorImplementation
76 {
77 struct Implementation;
78 }
79
80 namespace hp
81 {
82 namespace DoFHandlerImplementation
83 {
84 struct Implementation;
85 }
86 } // namespace hp
87 } // namespace internal
88
89 namespace parallel
90 {
91 namespace distributed
92 {
93 template <int dim, int spacedim, typename VectorType>
94 class CellDataTransfer;
95 }
96 } // namespace parallel
97
98 template <int structdim, int dim, int spacedim, bool level_dof_access>
99 class DoFAccessor;
100
101 template <int dimension_, int space_dimension_, bool level_dof_access>
102 class DoFCellAccessor;
103
104 #endif
105
106 /**
107 * Given a triangulation and a description of a finite element, this
108 * class enumerates degrees of freedom on all vertices, edges, faces,
109 * and cells of the triangulation. As a result, it also provides a
110 * <i>basis</i> for a discrete space $V_h$ whose elements are finite
111 * element functions defined on each cell by a FiniteElement object.
112 * This class satisfies the
113 * @ref ConceptMeshType "MeshType concept"
114 * requirements.
115 *
116 * It is first used in the step-2 tutorial program.
117 *
118 * For each 0d, 1d, 2d, and 3d subobject, this class stores a list of the
119 * indices of degrees of freedom defined on this DoFHandler. These indices
120 * refer to the unconstrained degrees of freedom, i.e. constrained degrees of
121 * freedom are numbered in the same way as unconstrained ones, and are only
122 * later eliminated. This leads to the fact that indices in global vectors
123 * and matrices also refer to all degrees of freedom and some kind of
124 * condensation is needed to restrict the systems of equations to the
125 * unconstrained degrees of freedom only. The actual layout of storage of the
126 * indices is described in the
127 * dealii::internal::DoFHandlerImplementation::DoFLevel class documentation.
128 *
129 * The class offers iterators to traverse all cells, in much the same way as
130 * the Triangulation class does. Using the begin() and end() functions (and
131 * companions, like begin_active()), one can obtain iterators to walk over
132 * cells, and query the degree of freedom structures as well as the
133 * triangulation data. These iterators are built on top of those of the
134 * Triangulation class, but offer the additional information on degrees of
135 * freedom functionality compared to pure triangulation iterators. The order
136 * in which dof iterators are presented by the <tt>++</tt> and <tt>\--</tt>
137 * operators is the same as that for the corresponding iterators traversing
138 * the triangulation on which this DoFHandler is constructed.
139 *
140 * The <tt>spacedim</tt> parameter has to be used if one wants to solve
141 * problems on surfaces. If not specified, this parameter takes the default
142 * value <tt>=dim</tt> implying that we want to solve problems in a domain
143 * whose dimension equals the dimension of the space in which it is embedded.
144 *
145 *
146 * <h3>Distribution of indices for degrees of freedom</h3>
147 *
148 * The degrees of freedom (`dofs') are distributed on the given triangulation
149 * by the function distribute_dofs(). It gets passed a finite element object
150 * describing how many degrees of freedom are located on vertices, lines, etc.
151 * It traverses the triangulation cell by cell and numbers the dofs of that
152 * cell if not yet numbered. For non-multigrid algorithms, only active cells
153 * are considered. Active cells are defined to be those cells which have no
154 * children, i.e. they are the most refined ones.
155 *
156 * Since the triangulation is traversed starting with the cells of the
157 * coarsest active level and going to more refined levels, the lowest numbers
158 * for dofs are given to the largest cells as well as their bounding lines and
159 * vertices, with the dofs of more refined cells getting higher numbers.
160 *
161 * This numbering implies very large bandwidths of the resulting matrices and
162 * is thus vastly suboptimal for some solution algorithms. For this reason,
163 * the DoFRenumbering class offers several algorithms to reorder the dof
164 * numbering according. See there for a discussion of the implemented
165 * algorithms.
166 *
167 *
168 * <h3>Interaction with distributed meshes</h3>
169 *
170 * Upon construction, this class takes a reference to a triangulation object.
171 * In most cases, this will be a reference to an object of type Triangulation,
172 * i.e. the class that represents triangulations that entirely reside on a
173 * single processor. However, it can also be of type
174 * parallel::distributed::Triangulation (see, for example, step-32, step-40
175 * and in particular the
176 * @ref distributed
177 * topic) in which case the DoFHandler object will proceed to only manage
178 * degrees of freedom on locally owned and ghost cells. This process is
179 * entirely transparent to the used.
180 *
181 *
182 * <h3>User defined renumbering schemes</h3>
183 *
184 * The DoFRenumbering class offers a number of renumbering schemes like the
185 * Cuthill-McKee scheme. Basically, the function sets up an array in which for
186 * each degree of freedom we store the new index this DoF should have after
187 * renumbering. Using this array, the renumber_dofs() function of the present
188 * class is called, which actually performs the change from old DoF indices to
189 * the ones given in the array. In some cases, however, a user may want to
190 * compute their own renumbering order; in this case, one can allocate an array
191 * with one element per degree of freedom and fill it with the number that the
192 * respective degree of freedom shall be assigned. This number may, for
193 * example, be obtained by sorting the support points of the degrees of
194 * freedom in downwind direction. Then call the
195 * <tt>renumber_dofs(vector<types::global_dof_index>)</tt> function with the
196 * array, which converts old into new degree of freedom indices.
197 *
198 *
199 * <h3>Serializing (loading or storing) DoFHandler objects</h3>
200 *
201 * Like many other classes in deal.II, the DoFHandler class can stream its
202 * contents to an archive using BOOST's serialization facilities. The data so
203 * stored can later be retrieved again from the archive to restore the
204 * contents of this object. This facility is frequently used to save the state
205 * of a program to disk for possible later resurrection, often in the context
206 * of checkpoint/restart strategies for long running computations or on
207 * computers that aren't very reliable (e.g. on very large clusters where
208 * individual nodes occasionally fail and then bring down an entire MPI job).
209 *
210 * The model for doing so is similar for the DoFHandler class as it is for the
211 * Triangulation class (see the section in the general documentation of that
212 * class). In particular, the load() function does not exactly restore the
213 * same state as was stored previously using the save() function. Rather, the
214 * function assumes that you load data into a DoFHandler object that is
215 * already associated with a triangulation that has a content that matches the
216 * one that was used when the data was saved. Likewise, the load() function
217 * assumes that the current object is already associated with a finite element
218 * object that matches the one that was associated with it when data was
219 * saved; the latter can be achieved by calling DoFHandler::distribute_dofs()
220 * using the same kind of finite element before re-loading data from the
221 * serialization archive.
222 *
223 *
224 * <h3>hp-adaptive finite element methods</h3>
225 *
226 * Instead of only using one particular FiniteElement on all cells, this class
227 * also allows for an enumeration of degrees of freedom on different finite
228 * elements on every cells. To this end, one assigns an
229 * <code>active_fe_index</code> to every cell that indicates which element
230 * within a collection of finite elements (represented by an object of type
231 * hp::FECollection) is the one that lives on this cell. The class then
232 * enumerates the degree of freedom associated with these finite elements on
233 * each cell of a triangulation and, if possible, identifies degrees of
234 * freedom at the interfaces of cells if they match. If neighboring cells
235 * have degrees of freedom along the common interface that do not immediate
236 * match (for example, if you have $Q_2$ and $Q_3$ elements meeting at a
237 * common face), then one needs to compute constraints to ensure that the
238 * resulting finite element space on the mesh remains conforming.
239 *
240 * The whole process of working with objects of this type is explained in
241 * step-27. Many of the algorithms this class implements are described in
242 * the
243 * @ref hp_paper "hp-paper".
244 *
245 *
246 * <h3>Active FE indices and their behavior under mesh refinement</h3>
247 *
248 * The typical workflow for using this class is to create a mesh, assign an
249 * active FE index to every active cell, call DoFHandler::distribute_dofs(),
250 * and then assemble a linear system and solve a problem on this finite element
251 * space.
252 *
253 * Active FE indices will be automatically transferred during mesh adaptation
254 * from the old to the new mesh. Future FE indices are meant to determine the
255 * active FE index after mesh adaptation, and are used to prepare data on the
256 * old mesh for the new one. If no future FE index is specified, the finite
257 * element prevails.
258 *
259 * In particular, the following rules apply during adaptation:
260 * - Upon mesh refinement, child cells inherit the future FE index of
261 * the parent.
262 * - When coarsening cells, the (now active) parent cell will be assigned
263 * a future FE index that is determined from its (no longer active)
264 * children, following the FiniteElementDomination logic: Out of the set of
265 * elements previously assigned to the former children, we choose the one
266 * dominated by all children for the parent cell. If none was found, we pick
267 * the most dominant element in the whole collection that is dominated by
268 * all former children. See hp::FECollection::find_dominated_fe_extended()
269 * for further information on this topic.
270 *
271 * Strategies for automatic hp-adaptation which will set future FE indices based
272 * on criteria are available in the hp::Refinement namespace.
273 *
274 *
275 * <h3>Active FE indices and parallel meshes</h3>
276 *
277 * When this class is used with either a parallel::shared::Triangulation
278 * or a parallel::distributed::Triangulation, you can only set active
279 * FE indices on cells that are locally owned,
280 * using a call such as <code>cell-@>set_active_fe_index(...)</code>.
281 * On the other hand, setting the active FE index on ghost
282 * or artificial cells is not allowed.
283 *
284 * Ghost cells do acquire the information what element
285 * is active on them, however: whenever you call DoFHandler::distribute_dofs(),
286 * all processors that participate in the parallel mesh exchange information in
287 * such a way that the active FE index on ghost cells equals the active FE index
288 * that was set on that processor that owned that particular ghost cell.
289 * Consequently, one can <i>query</i> the @p active_fe_index on ghost
290 * cells, just not set it by hand.
291 *
292 * On artificial cells, no information is available about the
293 * @p active_fe_index used there. That's because we don't even know
294 * whether these cells exist at all, and even if they did, the
295 * current processor does not know anything specific about them.
296 * See
297 * @ref GlossArtificialCell "the glossary entry on artificial cells"
298 * for more information.
299 *
300 * During refinement and coarsening, information about the @p active_fe_index
301 * of each cell will be automatically transferred.
302 *
303 * However, using a parallel::distributed::Triangulation with a DoFHandler
304 * in hp-mode requires additional attention during serialization, since no
305 * information on active FE indices will be automatically transferred. This
306 * has to be done manually using the
307 * prepare_for_serialization_of_active_fe_indices() and
308 * deserialize_active_fe_indices() functions. The former has to be called
309 * before parallel::distributed::Triangulation::save() is invoked, and the
310 * latter needs to be run after parallel::distributed::Triangulation::load().
311 * If further data will be attached to the triangulation via the
312 * parallel::distributed::CellDataTransfer,
313 * parallel::distributed::SolutionTransfer, or Particles::ParticleHandler
314 * classes, all corresponding preparation and deserialization function calls
315 * need to happen in the same order. Consult the documentation of
316 * parallel::distributed::SolutionTransfer for more information.
317 *
318 * @ingroup dofs
319 *
320 * @dealiiConceptRequires{(concepts::is_valid_dim_spacedim<dim, spacedim>)}
321 */
322 template <int dim, int spacedim = dim>
323 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
324 class DoFHandler : public EnableObserverPointer
325 {
326 using ActiveSelector =
327 dealii::internal::DoFHandlerImplementation::Iterators<dim, spacedim, false>;
328 using LevelSelector =
329 dealii::internal::DoFHandlerImplementation::Iterators<dim, spacedim, true>;
330
331 public:
332 /**
333 * An alias that is used to identify cell iterators in DoFHandler objects.
334 * The concept of iterators is discussed at length in the
335 * @ref Iterators "iterators documentation topic".
336 *
337 * The current alias works, in essence, like the corresponding
338 * Triangulation::cell_accessor alias. However, it also makes available
339 * the member functions of DoFCellAccessor, in addition to the ones
340 * already available through the CellAccessor class.
341 *
342 * @ingroup Iterators
343 */
344 using cell_accessor = typename ActiveSelector::CellAccessor;
345
346 /**
347 * An alias that is used to identify iterators that point to faces.
348 * The concept of iterators is discussed at length in the
349 * @ref Iterators "iterators documentation topic".
350 *
351 * The current alias works, in essence, like the corresponding
352 * Triangulation::face_accessor alias. However, it also makes available
353 * the member functions of DoFAccessor, in addition to the ones
354 * already available through the TriaAccessor class.
355 *
356 * @ingroup Iterators
357 */
358 using face_accessor = typename ActiveSelector::FaceAccessor;
359
360 /**
361 * An alias that defines an iterator over the (one-dimensional) lines
362 * of a mesh. In one-dimensional meshes, these are the cells of the mesh,
363 * whereas in two-dimensional meshes the lines are the faces of cells.
364 *
365 * @ingroup Iterators
366 */
367 using line_iterator = typename ActiveSelector::line_iterator;
368
369 /**
370 * An alias that allows iterating over the <i>active</i> lines, i.e.,
371 * that subset of lines that have no children. In one-dimensional meshes,
372 * these are the cells of the mesh, whereas in two-dimensional
373 * meshes the lines are the faces of cells.
374 *
375 * In two- or three-dimensional meshes, lines without children (i.e.,
376 * the active lines) are part of at least one active cell. Each such line may
377 * additionally be a child of a line of a coarser cell adjacent to a cell
378 * that is active. (This coarser neighbor would then also be active.)
379 *
380 * @ingroup Iterators
381 */
382 using active_line_iterator = typename ActiveSelector::active_line_iterator;
383
384 /**
385 * An alias that defines an iterator over the (two-dimensional) quads
386 * of a mesh. In two-dimensional meshes, these are the cells of the mesh,
387 * whereas in three-dimensional meshes the quads are the faces of cells.
388 *
389 * @ingroup Iterators
390 */
391 using quad_iterator = typename ActiveSelector::quad_iterator;
392
393 /**
394 * An alias that allows iterating over the <i>active</i> quads, i.e.,
395 * that subset of quads that have no children. In two-dimensional meshes,
396 * these are the cells of the mesh, whereas in three-dimensional
397 * meshes the quads are the faces of cells.
398 *
399 * In three-dimensional meshes, quads without children (i.e.,
400 * the active quads) are faces of at least one active cell. Each such quad may
401 * additionally be a child of a quad face of a coarser cell adjacent to a cell
402 * that is active. (This coarser neighbor would then also be active.)
403 *
404 * @ingroup Iterators
405 */
406 using active_quad_iterator = typename ActiveSelector::active_quad_iterator;
407
408 /**
409 * An alias that defines an iterator over the (three-dimensional) hexes
410 * of a mesh. This iterator only makes sense in three-dimensional meshes,
411 * where hexes are the cells of the mesh.
412 *
413 * @ingroup Iterators
414 */
415 using hex_iterator = typename ActiveSelector::hex_iterator;
416
417 /**
418 * An alias that allows iterating over the <i>active</i> hexes of a mesh.
419 * This iterator only makes sense in three-dimensional meshes,
420 * where hexes are the cells of the mesh. Consequently, in these
421 * three-dimensional meshes, this iterator is equivalent to the
422 * @p active_cell_iterator alias.
423 *
424 * @ingroup Iterators
425 */
426 using active_hex_iterator = typename ActiveSelector::active_hex_iterator;
427
428 /**
429 * An alias that is used to identify
430 * @ref GlossActive "active cell iterators".
431 * The concept of iterators is discussed at length in the
432 * @ref Iterators "iterators documentation topic".
433 *
434 * The current alias identifies active cells in a DoFHandler object. While
435 * the actual data type of the alias is hidden behind a few layers of
436 * (unfortunately necessary) indirections, it is in essence
437 * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator class works
438 * like a pointer to active objects that when you dereference it yields an
439 * object of type DoFCellAccessor. DoFCellAccessor is a class that
440 * identifies properties that are specific to cells in a DoFHandler, but it
441 * is derived (and consequently inherits) from both DoFAccessor,
442 * TriaCellAccessor and TriaAccessor that describe what you can ask of more
443 * general objects (lines, faces, as well as cells) in a triangulation and
444 * DoFHandler objects.
445 *
446 * @ingroup Iterators
447 */
448 using active_cell_iterator = typename ActiveSelector::active_cell_iterator;
449
450 /**
451 * An alias that is used to identify cell iterators. The concept of
452 * iterators is discussed at length in the
453 * @ref Iterators "iterators documentation topic".
454 *
455 * The current alias identifies cells in a DoFHandler object. Some of
456 * these cells may in fact be active (see
457 * @ref GlossActive "active cell iterators")
458 * in which case they can in fact be asked for the degrees of freedom that
459 * live on them. On the other hand, if the cell is not active, any such
460 * query will result in an error. Note that this is what distinguishes this
461 * alias from the level_cell_iterator alias.
462 *
463 * While the actual data type of the alias is hidden behind a few layers
464 * of (unfortunately necessary) indirections, it is in essence
465 * TriaIterator<DoFCellAccessor>. The TriaIterator class works like a
466 * pointer to objects that when you dereference it yields an object of type
467 * DoFCellAccessor. DoFCellAccessor is a class that identifies properties
468 * that are specific to cells in a DoFHandler, but it is derived (and
469 * consequently inherits) from both DoFAccessor, TriaCellAccessor and
470 * TriaAccessor that describe what you can ask of more general objects
471 * (lines, faces, as well as cells) in a triangulation and DoFHandler
472 * objects.
473 *
474 * @ingroup Iterators
475 */
476 using cell_iterator = typename ActiveSelector::cell_iterator;
477
478 /**
479 * An alias that is used to identify iterators that point to faces.
480 * The concept of iterators is discussed at length in the
481 * @ref Iterators "iterators documentation topic".
482 *
483 * While the actual data type of the alias is hidden behind a few layers
484 * of (unfortunately necessary) indirections, it is in essence
485 * TriaIterator<DoFAccessor>. The
486 * TriaIterator class works like a pointer to objects that when
487 * you dereference it yields an object of type DoFAccessor. DoFAccessor,
488 * in turn, is a class that can be used to query DoF indices on faces,
489 * but it is also derived from TriaAccessor and consequently can be used
490 * to query geometric properties such as vertices of faces, their area, etc.
491 *
492 * @ingroup Iterators
493 */
494 using face_iterator = typename ActiveSelector::face_iterator;
495
496 /**
497 * An alias that is used to identify iterators that point to active faces,
498 * i.e., to faces that have no children. Active faces must be faces of at
499 * least one active cell.
500 *
501 * Other than the "active" qualification, this alias is identical to the
502 * @p face_iterator alias. In particular, dereferencing either yields
503 * the same kind of object.
504 *
505 * @ingroup Iterators
506 */
507 using active_face_iterator = typename ActiveSelector::active_face_iterator;
508
509 using level_cell_accessor = typename LevelSelector::CellAccessor;
510 using level_face_accessor = typename LevelSelector::FaceAccessor;
511
512 using level_cell_iterator = typename LevelSelector::cell_iterator;
513 using level_face_iterator = typename LevelSelector::face_iterator;
514
515
516 /**
517 * Make the dimension available in function templates.
518 */
519 static constexpr unsigned int dimension = dim;
520
521 /**
522 * Make the space dimension available in function templates.
523 */
524 static constexpr unsigned int space_dimension = spacedim;
525
526 /**
527 * The default index of the finite element to be used on a given cell.
528 */
529 static const types::fe_index default_fe_index = 0;
530
531 /**
532 * The type in which we store the offsets in the CRS data structures.
533 */
534 using offset_type = unsigned int;
535
536 /**
537 * Standard constructor, not initializing any data. After constructing an
538 * object with this constructor, use reinit() to get a valid DoFHandler.
539 */
540 DoFHandler();
541
542 /**
543 * Constructor. Take @p tria as the triangulation to work on.
544 */
545 explicit DoFHandler(const Triangulation<dim, spacedim> &tria);
546
547 /**
548 * Copy constructor. DoFHandler objects are large and expensive.
549 * They should not be copied, in particular not by accident, but
550 * rather deliberately constructed. As a consequence, this constructor
551 * is explicitly removed from the interface of this class.
552 */
553 DoFHandler(const DoFHandler &) = delete;
554
555 /**
556 * Destructor.
557 */
558 virtual ~DoFHandler() override;
559
560 /**
561 * Copy operator. DoFHandler objects are large and expensive.
562 * They should not be copied, in particular not by accident, but
563 * rather deliberately constructed. As a consequence, this operator
564 * is explicitly removed from the interface of this class.
565 */
566 DoFHandler &
567 operator=(const DoFHandler &) = delete;
568
569 /**
570 * For each locally owned cell, set the active finite element index to the
571 * corresponding value given in @p active_fe_indices.
572 *
573 * The vector @p active_fe_indices needs to have as many entries as there
574 * are active cells. The FE indices must be in the order in which we iterate
575 * over active cells. Vector entries corresponding to active cells that are
576 * not locally owned are ignored.
577 *
578 * Active FE indices will only be set for locally owned cells. Ghost and
579 * artificial cells will be ignored; no active FE index will be assigned to
580 * them. To exchange active FE indices on ghost cells, call distribute_dofs()
581 * afterwards.
582 */
583 void
584 set_active_fe_indices(const std::vector<types::fe_index> &active_fe_indices);
585
586 /**
587 * @copydoc set_active_fe_indices()
588 *
589 * @deprecated Use set_active_fe_indices() with the types::fe_index datatype.
590 */
591 DEAL_II_DEPRECATED
592 void
593 set_active_fe_indices(const std::vector<unsigned int> &active_fe_indices);
594
595 /**
596 * For each locally relevant cell, extract the active finite element index and
597 * return them in the order in which we iterate over active cells.
598 *
599 * As we do not know the active FE index on artificial cells, they are set to
600 * the invalid value numbers::invalid_fe_index.
601 *
602 * For DoFHandler objects without hp-capabilities, the vector will consist of
603 * zeros, indicating that all cells use the same finite element. In hp-mode,
604 * the values may be different, though.
605 *
606 * The returned vector has as many entries as there are active cells.
607 */
608 std::vector<types::fe_index>
609 get_active_fe_indices() const;
610
611 /**
612 * For each locally relevant cell, extract the active finite element index and
613 * fill the vector @p active_fe_indices in the order in which we iterate over
614 * active cells. This vector is resized, if necessary.
615 *
616 * As we do not know the active FE index on artificial cells, they are set to
617 * the invalid value numbers::invalid_fe_index.
618 *
619 * For DoFHandler objects without hp-capabilities, the vector will consist of
620 * zeros, indicating that all cells use the same finite element. In hp-mode,
621 * the values may be different, though.
622 *
623 * The returned vector has as many entries as there are active cells.
624 *
625 * @deprecated Use get_active_fe_indices() that returns the result vector.
626 */
627 DEAL_II_DEPRECATED
628 void
629 get_active_fe_indices(std::vector<unsigned int> &active_fe_indices) const;
630
631 /**
632 * For each locally owned cell, set the future finite element index to the
633 * corresponding value given in @p future_fe_indices.
634 *
635 * The vector @p future_fe_indices needs to have as many entries as there
636 * are active cells. The FE indices must be in the order in which we iterate
637 * over active cells. Vector entries corresponding to active cells that are
638 * not locally owned are ignored.
639 *
640 * Future FE indices will only be set for locally owned cells. Ghost and
641 * artificial cells will be ignored; no future FE index will be assigned to
642 * them.
643 */
644 void
645 set_future_fe_indices(const std::vector<types::fe_index> &future_fe_indices);
646
647 /**
648 * For each locally owned cell, extract the future finite element index and
649 * return them in the order in which we iterate over active cells.
650 *
651 * As we do not know the future FE index on ghost and artificial cells, they
652 * are set to the invalid value numbers::invalid_fe_index. The same applies to
653 * locally owned cells that have no future FE index assigned.
654 *
655 * The returned vector has as many entries as there are active cells.
656 */
657 std::vector<types::fe_index>
658 get_future_fe_indices() const;
659
660 /**
661 * Assign a Triangulation to the DoFHandler.
662 *
663 * Remove all associations with the previous Triangulation object and
664 * establish connections with the new one. All information about previous
665 * degrees of freedom will be removed. Activates hp-mode.
666 */
667 void
668 reinit(const Triangulation<dim, spacedim> &tria);
669
670 /**
671 * Go through the triangulation and "distribute" the degrees of
672 * freedom needed for the given finite element. "Distributing"
673 * degrees of freedom involves allocating memory to store the
674 * indices on all entities on which degrees of freedom can be
675 * located (e.g., vertices, edges, faces, etc.) and to then enumerate
676 * all degrees of freedom. In other words, while the mesh and the
677 * finite element object by themselves simply define a finite
678 * element space $V_h$, the process of distributing degrees of
679 * freedom makes sure that there is a basis for this space and that
680 * the shape functions of this basis are enumerated in an indexable,
681 * predictable way.
682 *
683 * The exact order in which degrees of freedom on a mesh are
684 * ordered, i.e., the order in which basis functions of the finite
685 * element space are enumerated, is something that deal.II treats as
686 * an implementation detail. By and large, degrees of freedom are
687 * enumerated in the same order in which we traverse cells, but you
688 * should not rely on any specific numbering. In contrast, if you
689 * want a particular ordering, use the functions in namespace
690 * DoFRenumbering.
691 *
692 * This function is first discussed in the introduction to the
693 * step-2 tutorial program.
694 *
695 * @note This function makes a copy of the finite element given as
696 * argument, and stores it as a member variable, similarly to the above
697 * function set_fe().
698 */
699 void
700 distribute_dofs(const FiniteElement<dim, spacedim> &fe);
701
702 /**
703 * Same as above but taking an hp::FECollection object.
704 */
705 void
706 distribute_dofs(const hp::FECollection<dim, spacedim> &fe);
707
708 /**
709 * Distribute level degrees of freedom on each level for geometric
710 * multigrid. The active DoFs need to be distributed using distribute_dofs()
711 * before calling this function.
712 */
713 void
714 distribute_mg_dofs();
715
716 /**
717 * Returns whether this DoFHandler has hp-capabilities.
718 */
719 bool
720 has_hp_capabilities() const;
721
722 /**
723 * This function returns whether this DoFHandler has DoFs distributed on
724 * each multigrid level or in other words if distribute_mg_dofs() has been
725 * called.
726 */
727 bool
728 has_level_dofs() const;
729
730 /**
731 * This function returns whether this DoFHandler has active DoFs. This is
732 * equivalent to asking whether (i) distribute_dofs() has been called and
733 * (ii) the finite element for which degrees of freedom have been
734 * distributed actually has degrees of freedom (which is not the case for
735 * FE_Nothing, for example).
736 *
737 * If this object is based on a parallel::distributed::Triangulation, then
738 * the current function returns true if <i>any</i> partition of the parallel
739 * DoFHandler object has any degrees of freedom. In other words, the
740 * function returns true even if the Triangulation does not own any active
741 * cells on the current MPI process, but at least one process owns cells and
742 * at least this one process has any degrees of freedom associated with it.
743 */
744 bool
745 has_active_dofs() const;
746
747 /**
748 * After distribute_dofs() with an FESystem element, the block structure of
749 * global and level vectors is stored in a BlockInfo object accessible with
750 * block_info(). This function initializes the local block structure on each
751 * cell in the same object.
752 */
753 void
754 initialize_local_block_info();
755
756 /**
757 * Clear all data of this object.
758 */
759 void
760 clear();
761
762 /**
763 * Renumber degrees of freedom based on a list of new DoF indices for each
764 * of the degrees of freedom.
765 *
766 * This function is called by the functions in DoFRenumbering function after
767 * computing a new ordering of the degree of freedom indices. However, it
768 * can of course also be called from user code.
769 *
770 * @arg new_number This array must have a size equal to the number of
771 * degrees of freedom owned by the current processor, i.e. the size must be
772 * equal to what n_locally_owned_dofs() returns. If only one processor
773 * participates in storing the current mesh, then this equals the total
774 * number of degrees of freedom, i.e. the result of n_dofs(). The contents
775 * of this array are the new global indices for each freedom listed in the
776 * IndexSet returned by locally_owned_dofs(). In the case of a sequential
777 * mesh this means that the array is a list of new indices for each of the
778 * degrees of freedom on the current mesh. In the case that we have a
779 * parallel::shared::Triangulation or
780 * parallel::distributed::Triangulation underlying this DoFHandler object,
781 * the array is a list of new indices for all the locally owned degrees of
782 * freedom, enumerated in the same order as the currently locally owned
783 * DoFs. In other words, assume that degree of freedom <code>i</code> is
784 * currently locally owned, then
785 * <code>new_numbers[locally_owned_dofs().index_within_set(i)]</code>
786 * returns the new global DoF index of <code>i</code>. Since the IndexSet of
787 * locally_owned_dofs() is complete in the sequential case, the latter
788 * convention for the content of the array reduces to the former in the case
789 * that only one processor participates in the mesh.
790 *
791 * @note While it follows from the above, it may be surprising to know that
792 * the <i>number</i> of locally owned degrees of freedom in a parallel
793 * computation is an invariant
794 * under renumbering, even if the <i>indices</i> associated with these
795 * locally owned degrees of freedom are not. At a fundamental level,
796 * this invariant exists because the <i>decision</i> whether a degree of
797 * freedom is locally owned or not has nothing to do with that
798 * degree of freedom's (old or new) index. Indeed, degrees of freedom
799 * are locally owned if they are on a locally owned cell and not on
800 * an interface between cells where the neighboring cell has a lower
801 * @ref GlossSubdomainId "subdomain id". Since both of these conditions
802 * are independent of the index associated with the DoF, a locally
803 * owned degree of freedom will also be locally owned after renumbering.
804 * On the other hand, properties such as whether the set of indices
805 * of locally owned DoFs forms a contiguous range or not
806 * (i.e., whether the locally_owned_dofs() returns an IndexSet object
807 * for which IndexSet::is_contiguous() returns @p true) are of
808 * course affected by the exact renumbering performed here. For example,
809 * while the initial numbering of DoF indices done in distribute_dofs()
810 * yields a contiguous numbering, the renumbering performed by
811 * DoFRenumbering::component_wise() will, in general, not yield
812 * contiguous locally owned DoF indices.
813 */
814 void
815 renumber_dofs(const std::vector<types::global_dof_index> &new_numbers);
816
817 /**
818 * The same function as above, but renumber the degrees of freedom of a
819 * single level of a multigrid hierarchy.
820 */
821 void
822 renumber_dofs(const unsigned int level,
823 const std::vector<types::global_dof_index> &new_numbers);
824
825 /**
826 * Return the maximum number of degrees of freedom a degree of freedom in
827 * the given triangulation with the given finite element may couple with.
828 * This is the maximum number of entries per line in the system matrix; this
829 * information can therefore be used upon construction of the
830 * SparsityPattern object.
831 *
832 * The returned number is not really the maximum number but an estimate
833 * based on the finite element and the maximum number of cells meeting at a
834 * vertex. The number holds for the constrained matrix as well.
835 *
836 * The determination of the number of couplings can be done by simple
837 * picture drawing. An example can be found in the implementation of this
838 * function.
839 *
840 * @note This function is most often used to determine the maximal row
841 * length for sparsity patterns. Unfortunately, while the estimates returned
842 * by this function are rather accurate in 1d and 2d, they are often
843 * significantly too high in 3d, leading the SparsityPattern class to
844 * allocate much too much memory in some cases. Unless someone comes around
845 * to improving the present function for 3d, there is not very much one can
846 * do about these cases. The typical way to work around this problem is to
847 * use an intermediate compressed sparsity pattern that only allocates
848 * memory on demand. Refer to the step-2 and step-11 example programs on how
849 * to do this. The problem is also discussed in the documentation of the
850 * topic on
851 * @ref Sparsity.
852 */
853 unsigned int
854 max_couplings_between_dofs() const;
855
856 /**
857 * Return the number of degrees of freedom located on the boundary another
858 * dof on the boundary can couple with.
859 *
860 * The number is the same as for max_couplings_between_dofs() in one
861 * dimension less.
862 *
863 * @note The same applies to this function as to max_couplings_between_dofs() as
864 * regards the performance of this function. Think about one of the dynamic
865 * sparsity pattern classes instead (see
866 * @ref Sparsity).
867 */
868 unsigned int
869 max_couplings_between_boundary_dofs() const;
870
871 /*--------------------------------------*/
872
873 /**
874 * @name Cell iterator functions
875 */
876
877 /** @{ */
878
879 /**
880 * Iterator to the first used cell on level @p level.
881 */
882 cell_iterator
883 begin(const unsigned int level = 0) const;
884
885 /**
886 * Iterator to the first active cell on level @p level. If the given level
887 * does not contain any active cells (i.e., all cells on this level are
888 * further refined), then this function returns
889 * <code>end_active(level)</code> so that loops of the kind
890 * @code
891 * for (cell=dof_handler.begin_active(level);
892 * cell!=dof_handler.end_active(level);
893 * ++cell)
894 * {
895 * ...
896 * }
897 * @endcode
898 * have zero iterations, as may be expected if there are no active cells on
899 * this level.
900 */
901 active_cell_iterator
902 begin_active(const unsigned int level = 0) const;
903
904 /**
905 * Iterator past the end; this iterator serves for comparisons of iterators
906 * with past-the-end or before-the-beginning states.
907 */
908 cell_iterator
909 end() const;
910
911 /**
912 * Return an iterator which is the first iterator not on the given level. If
913 * @p level is the last level, then this returns <tt>end()</tt>.
914 */
915 cell_iterator
916 end(const unsigned int level) const;
917
918 /**
919 * Return an active iterator which is the first active iterator not on the
920 * given level. If @p level is the last level, then this returns
921 * <tt>end()</tt>.
922 */
923 active_cell_iterator
924 end_active(const unsigned int level) const;
925
926 /**
927 * Iterator to the first used cell on level @p level. This returns a
928 * level_cell_iterator that returns level dofs when dof_indices() is called.
929 */
930 level_cell_iterator
931 begin_mg(const unsigned int level = 0) const;
932
933 /**
934 * Iterator past the last cell on level @p level. This returns a
935 * level_cell_iterator that returns level dofs when dof_indices() is called.
936 */
937 level_cell_iterator
938 end_mg(const unsigned int level) const;
939
940 /**
941 * Iterator past the end; this iterator serves for comparisons of iterators
942 * with past-the-end or before-the-beginning states.
943 */
944 level_cell_iterator
945 end_mg() const;
946 /** @} */
947
948 /**
949 * @name Cell iterator functions returning ranges of iterators
950 */
951
952 /** @{ */
953 /**
954 * Return an iterator range that contains all cells (active or not) that
955 * make up this DoFHandler. Such a range is useful to initialize range-based
956 * for loops as supported by C++11. See the example in the documentation of
957 * active_cell_iterators().
958 *
959 * @return The half open range <code>[this->begin(), this->end())</code>
960 *
961 * @ingroup CPP11
962 */
963 IteratorRange<cell_iterator>
964 cell_iterators() const;
965
966 /**
967 * Return an iterator range that contains all active cells that make up this
968 * DoFHandler. Such a range is useful to initialize range-based for loops as
969 * supported by C++11, see also
970 * @ref CPP11 "C++11 standard".
971 *
972 * Range-based for loops are useful in that they require much less code than
973 * traditional loops (see <a href="http://en.wikipedia.org/wiki/C%2B%2B11
974 * #Range-based_for_loop">here</a> for a discussion of how they work). An
975 * example is that without range-based for loops, one often writes code such
976 * as the following:
977 * @code
978 * DoFHandler<dim> dof_handler;
979 * ...
980 * typename DoFHandler<dim>::active_cell_iterator
981 * cell = dof_handler.begin_active(),
982 * endc = dof_handler.end();
983 * for (; cell!=endc; ++cell)
984 * {
985 * fe_values.reinit (cell);
986 * ...do the local integration on 'cell'...;
987 * }
988 * @endcode
989 * Using C++11's range-based for loops, this is now entirely equivalent to
990 * the following:
991 * @code
992 * DoFHandler<dim> dof_handler;
993 * ...
994 * for (const auto &cell : dof_handler.active_cell_iterators())
995 * {
996 * fe_values.reinit (cell);
997 * ...do the local integration on 'cell'...;
998 * }
999 * @endcode
1000 *
1001 * @return The half open range <code>[this->begin_active(),
1002 * this->end())</code>
1003 *
1004 * @ingroup CPP11
1005 */
1006 IteratorRange<active_cell_iterator>
1007 active_cell_iterators() const;
1008
1009 /**
1010 * Return an iterator range that contains all cells (active or not) that
1011 * make up this DoFHandler in their level-cell form. Such a range is useful
1012 * to initialize range-based for loops as supported by C++11. See the
1013 * example in the documentation of active_cell_iterators().
1014 *
1015 * @return The half open range <code>[this->begin_mg(),
1016 * this->end_mg())</code>
1017 *
1018 * @ingroup CPP11
1019 */
1020 IteratorRange<level_cell_iterator>
1021 mg_cell_iterators() const;
1022
1023 /**
1024 * Return an iterator range that contains all cells (active or not) that
1025 * make up the given level of this DoFHandler. Such a range is useful to
1026 * initialize range-based for loops as supported by C++11. See the example
1027 * in the documentation of active_cell_iterators().
1028 *
1029 * @param[in] level A given level in the refinement hierarchy of this
1030 * triangulation.
1031 * @return The half open range <code>[this->begin(level),
1032 * this->end(level))</code>
1033 *
1034 * @pre level must be less than this->n_levels().
1035 *
1036 * @ingroup CPP11
1037 */
1038 IteratorRange<cell_iterator>
1039 cell_iterators_on_level(const unsigned int level) const;
1040
1041 /**
1042 * Return an iterator range that contains all active cells that make up the
1043 * given level of this DoFHandler. Such a range is useful to initialize
1044 * range-based for loops as supported by C++11. See the example in the
1045 * documentation of active_cell_iterators().
1046 *
1047 * @param[in] level A given level in the refinement hierarchy of this
1048 * triangulation.
1049 * @return The half open range <code>[this->begin_active(level),
1050 * this->end(level))</code>
1051 *
1052 * @pre level must be less than this->n_levels().
1053 *
1054 * @ingroup CPP11
1055 */
1056 IteratorRange<active_cell_iterator>
1057 active_cell_iterators_on_level(const unsigned int level) const;
1058
1059 /**
1060 * Return an iterator range that contains all cells (active or not) that
1061 * make up the given level of this DoFHandler in their level-cell form. Such
1062 * a range is useful to initialize range-based for loops as supported by
1063 * C++11. See the example in the documentation of active_cell_iterators().
1064 *
1065 * @param[in] level A given level in the refinement hierarchy of this
1066 * triangulation.
1067 * @return The half open range <code>[this->begin_mg(level),
1068 * this->end_mg(level))</code>
1069 *
1070 * @pre level must be less than this->n_levels().
1071 *
1072 * @ingroup CPP11
1073 */
1074 IteratorRange<level_cell_iterator>
1075 mg_cell_iterators_on_level(const unsigned int level) const;
1076
1077 /** @} */
1078
1079
1080 /*---------------------------------------*/
1081
1082
1083 /**
1084 * Return the global number of degrees of freedom. If the current object
1085 * handles all degrees of freedom itself (even if you may intend to solve
1086 * your linear system in parallel, such as in step-17 or step-18), then this
1087 * number equals the number of locally owned degrees of freedom since this
1088 * object doesn't know anything about what you want to do with it and
1089 * believes that it owns every degree of freedom it knows about.
1090 *
1091 * On the other hand, if this object operates on a
1092 * parallel::distributed::Triangulation object, then this function returns
1093 * the global number of degrees of freedom, accumulated over all processors.
1094 *
1095 * In either case, included in the returned number are those DoFs which are
1096 * constrained by hanging nodes, see
1097 * @ref constraints.
1098 *
1099 * Mathematically speaking, the number returned by this function equals the
1100 * dimension of the finite element space (without taking into account
1101 * constraints) that corresponds to (i) the mesh on which it is defined,
1102 * and (ii) the finite element that is used by the current object. It
1103 * also, of course, equals the number of shape functions that span this
1104 * space.
1105 */
1106 types::global_dof_index
1107 n_dofs() const;
1108
1109 /**
1110 * The (global) number of multilevel degrees of freedom on a given level.
1111 *
1112 * If no level degrees of freedom have been assigned to this level, returns
1113 * numbers::invalid_dof_index. Else returns the number of degrees of freedom
1114 * on this level.
1115 */
1116 types::global_dof_index
1117 n_dofs(const unsigned int level) const;
1118
1119 /**
1120 * Return the number of locally owned degrees of freedom located on the
1121 * boundary.
1122 */
1123 types::global_dof_index
1124 n_boundary_dofs() const;
1125
1126 /**
1127 * Return the number of locally owned degrees of freedom located on those
1128 * parts of the boundary which have a boundary indicator listed in the given
1129 * set.
1130 * The reason that a @p map rather than a @p set is used is the same as
1131 * described in the documentation of that variant of
1132 * DoFTools::make_boundary_sparsity_pattern() that takes a map.
1133 *
1134 * There is, however, another overload of this function that takes
1135 * a @p set argument (see below).
1136 */
1137 template <typename number>
1138 types::global_dof_index
1139 n_boundary_dofs(
1140 const std::map<types::boundary_id, const Function<spacedim, number> *>
1141 &boundary_ids) const;
1142
1143 /**
1144 * Return the number of degrees of freedom located on those parts of the
1145 * boundary which have a boundary indicator listed in the given set. The
1146 */
1147 types::global_dof_index
1148 n_boundary_dofs(const std::set<types::boundary_id> &boundary_ids) const;
1149
1150 /**
1151 * Access to an object informing of the block structure of the dof handler.
1152 *
1153 * If an FESystem is used in distribute_dofs(), degrees of freedom naturally
1154 * split into several
1155 * @ref GlossBlock "blocks".
1156 * For each base element as many blocks appear as its multiplicity.
1157 *
1158 * At the end of distribute_dofs(), the number of degrees of freedom in each
1159 * block is counted, and stored in a BlockInfo object, which can be accessed
1160 * here. If you have previously called distribute_mg_dofs(), the same is
1161 * done on each level of the multigrid hierarchy. Additionally, the block
1162 * structure on each cell can be generated in this object by calling
1163 * initialize_local_block_info().
1164 */
1165 const BlockInfo &
1166 block_info() const;
1167
1168 /**
1169 * Return the number of degrees of freedom that belong to this process.
1170 *
1171 * If this is a sequential DoFHandler, then the result equals that produced by
1172 * n_dofs(). (Here, "sequential" means that either
1173 * the whole program does not use MPI, or that it uses MPI
1174 * but only uses a single MPI process, or that there are multiple MPI
1175 * processes but the Triangulation on which this DoFHandler builds
1176 * works only on one MPI process.)
1177 * On the other hand, if we are operating on a
1178 * parallel::distributed::Triangulation or parallel::shared::Triangulation,
1179 * then it includes only the degrees
1180 * of freedom that the current processor owns. Note that in this case this
1181 * does not include all degrees of freedom that have been distributed on the
1182 * current processor's image of the mesh: in particular, some of the degrees
1183 * of freedom on the interface between the cells owned by this processor and
1184 * cells owned by other processors may be theirs, and degrees of freedom on
1185 * ghost cells are also not necessarily included.
1186 */
1187 types::global_dof_index
1188 n_locally_owned_dofs() const;
1189
1190 /**
1191 * Return an IndexSet describing the set of locally owned DoFs as a subset
1192 * of 0..n_dofs(). The number of elements of this set equals
1193 * n_locally_owned_dofs().
1194 */
1195 const IndexSet &
1196 locally_owned_dofs() const;
1197
1198 /**
1199 * Return an IndexSet describing the set of locally owned DoFs used for the
1200 * given multigrid level as a subset of 0..n_dofs(level).
1201 */
1202 const IndexSet &
1203 locally_owned_mg_dofs(const unsigned int level) const;
1204
1205 /**
1206 * Return a constant reference to the indexth finite element object that is
1207 * used by this object.
1208 */
1209 const FiniteElement<dim, spacedim> &
1210 get_fe(const types::fe_index index = 0) const;
1211
1212 /**
1213 * Return a constant reference to the set of finite element objects that
1214 * are used by this object.
1215 */
1216 const hp::FECollection<dim, spacedim> &
1217 get_fe_collection() const;
1218
1219 /**
1220 * Return a constant reference to the triangulation underlying this object.
1221 */
1222 const Triangulation<dim, spacedim> &
1223 get_triangulation() const;
1224
1225 /**
1226 * Return MPI communicator used by the underlying triangulation.
1227 */
1228 MPI_Comm
1229 get_mpi_communicator() const;
1230
1231 /**
1232 * Return MPI communicator used by the underlying triangulation.
1233 *
1234 * @deprecated Use get_mpi_communicator() instead.
1235 */
1236 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
1237 "Access the MPI communicator with get_mpi_communicator() instead.")
1238 MPI_Comm
1239 get_communicator() const;
1240
1241 /**
1242 * Whenever serialization with a parallel::distributed::Triangulation as the
1243 * underlying triangulation is considered, we also need to consider storing
1244 * the active FE indices on all active cells as well.
1245 *
1246 * This function registers that these indices are to be stored whenever the
1247 * parallel::distributed::Triangulation::save() function is called on the
1248 * underlying triangulation.
1249 *
1250 * @note Currently only implemented for triangulations of type
1251 * parallel::distributed::Triangulation. An assertion will be triggered if
1252 * a different type is registered.
1253 *
1254 * @see The documentation of parallel::distributed::SolutionTransfer has further
1255 * information on serialization.
1256 */
1257 void
1258 prepare_for_serialization_of_active_fe_indices();
1259
1260 /**
1261 * Whenever serialization with a parallel::distributed::Triangulation as the
1262 * underlying triangulation is considered, we also need to consider storing
1263 * the active FE indices on all active cells as well.
1264 *
1265 * This function deserializes and distributes the previously stored
1266 * active FE indices on all active cells.
1267 *
1268 * @note Currently only implemented for triangulations of type
1269 * parallel::distributed::Triangulation. An assertion will be triggered if
1270 * a different type is registered.
1271 *
1272 * @see The documentation of parallel::distributed::SolutionTransfer has further
1273 * information on serialization.
1274 */
1275 void
1276 deserialize_active_fe_indices();
1277
1278 /**
1279 * Determine an estimate for the memory consumption (in bytes) of this
1280 * object.
1281 *
1282 * This function is made virtual, since a dof handler object might be
1283 * accessed through a pointers to this base class, although the actual
1284 * object might be a derived class.
1285 */
1286 virtual std::size_t
1287 memory_consumption() const;
1288
1289 /**
1290 * Write the data of this object to a stream for the purpose of
1291 * serialization using the [BOOST serialization
1292 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1293 */
1294 template <class Archive>
1295 void
1296 save(Archive &ar, const unsigned int version) const;
1297
1298 /**
1299 * Read the data of this object from a stream for the purpose of
1300 * serialization using the [BOOST serialization
1301 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1302 */
1303 template <class Archive>
1304 void
1305 load(Archive &ar, const unsigned int version);
1306
1307 #ifdef DOXYGEN
1308 /**
1309 * Write and read the data of this object from a stream for the purpose
1310 * of serialization using the [BOOST serialization
1311 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1312 */
1313 template <class Archive>
1314 void
1315 serialize(Archive &archive, const unsigned int version);
1316 #else
1317 // This macro defines the serialize() method that is compatible with
1318 // the templated save() and load() method that have been implemented.
1319 BOOST_SERIALIZATION_SPLIT_MEMBER()
1320 #endif
1321
1322 /**
1323 * Exception
1324 */
1325 DeclException0(ExcNoFESelected);
1326 /**
1327 * Exception
1328 * @ingroup Exceptions
1329 */
1330 DeclException0(ExcInvalidBoundaryIndicator);
1331 /**
1332 * Exception
1333 * @ingroup Exceptions
1334 */
1335 DeclException1(ExcInvalidLevel,
1336 int,
1337 << "The given level " << arg1
1338 << " is not in the valid range!");
1339 /**
1340 * Exception
1341 * @ingroup Exceptions
1342 */
1343 DeclException1(ExcNewNumbersNotConsecutive,
1344 types::global_dof_index,
1345 << "The given list of new dof indices is not consecutive: "
1346 << "the index " << arg1 << " does not exist.");
1347 /**
1348 * Exception
1349 */
1350 DeclException2(ExcInvalidFEIndex,
1351 int,
1352 int,
1353 << "The mesh contains a cell with an active FE index of "
1354 << arg1 << ", but the finite element collection only has "
1355 << arg2 << " elements");
1356
1357 /**
1358 * Exception used when a certain feature doesn't make sense when
1359 * DoFHandler does not hp-capabilities.
1360 */
1361 DeclExceptionMsg(ExcOnlyAvailableWithHP,
1362 "The current function doesn't make sense when used with a "
1363 "DoFHandler without hp-capabilities.");
1364
1365 /**
1366 * Exception used when a certain feature is not implemented when the
1367 * DoFHandler has hp-capabilities.
1368 */
1369 DeclExceptionMsg(ExcNotImplementedWithHP,
1370 "The current function has not yet been implemented for a "
1371 "DoFHandler with hp-capabilities.");
1372
1373 private:
1374 /**
1375 * A data structure that is used to store the DoF indices associated with a
1376 * particular vertex. Unlike cells, vertices live on several levels of a
1377 * multigrid hierarchy; consequently, we need to store DoF indices for each
1378 * vertex for each of the levels it lives on. This class does this.
1379 */
1380 class MGVertexDoFs
1381 {
1382 public:
1383 /**
1384 * Constructor.
1385 */
1386 MGVertexDoFs();
1387
1388 /**
1389 * A function that is called to allocate the necessary amount of memory to
1390 * store the indices of the DoFs that live on this vertex for the given
1391 * (inclusive) range of levels.
1392 */
1393 void
1394 init(const unsigned int coarsest_level,
1395 const unsigned int finest_level,
1396 const unsigned int dofs_per_vertex);
1397
1398 /**
1399 * Return the coarsest level for which this structure stores data.
1400 */
1401 unsigned int
1402 get_coarsest_level() const;
1403
1404 /**
1405 * Return the finest level for which this structure stores data.
1406 */
1407 unsigned int
1408 get_finest_level() const;
1409
1410 /**
1411 * Return the index of the <code>dof_number</code>th degree of freedom for
1412 * the given level stored for the current vertex.
1413 */
1414 types::global_dof_index &
1415 access_index(const unsigned int level,
1416 const unsigned int dof_number,
1417 const unsigned int dofs_per_vertex);
1418
1419 private:
1420 /**
1421 * Coarsest level for which this object stores DoF indices.
1422 */
1423 unsigned int coarsest_level;
1424
1425 /**
1426 * Finest level for which this object stores DoF indices.
1427 */
1428 unsigned int finest_level;
1429
1430 /**
1431 * A pointer to an array where we store the indices of the DoFs that live
1432 * on the various levels this vertex exists on.
1433 *
1434 * The starting offset of the DoFs that belong to a @p level are given by
1435 * <code>n_dofs_per_vertex() * (level-coarsest_level)</code>. @p n_dofs_per_vertex()
1436 * must therefore be passed as an argument to the functions that set or
1437 * read an index.
1438 */
1439 std::unique_ptr<types::global_dof_index[]> indices;
1440 };
1441
1442 /**
1443 * Whenever the underlying triangulation changes by either
1444 * h/p-refinement/coarsening and serialization, the active FE index of cells
1445 * needs to be transferred. This structure stores all temporary information
1446 * required during that process.
1447 */
1448 struct ActiveFEIndexTransfer
1449 {
1450 /**
1451 * Container to temporarily store the iterator and future active FE index
1452 * of cells that persist.
1453 */
1454 std::map<const cell_iterator, const types::fe_index>
1455 persisting_cells_fe_index;
1456
1457 /**
1458 * Container to temporarily store the iterator and future active FE index
1459 * of cells that will be refined.
1460 */
1461 std::map<const cell_iterator, const types::fe_index> refined_cells_fe_index;
1462
1463 /**
1464 * Container to temporarily store the iterator and future active FE index
1465 * of parent cells that will remain after coarsening.
1466 */
1467 std::map<const cell_iterator, const types::fe_index>
1468 coarsened_cells_fe_index;
1469
1470 /**
1471 * Container to temporarily store the active FE index of every locally
1472 * owned cell for transfer across parallel::distributed::Triangulation
1473 * objects.
1474 */
1475 std::vector<types::fe_index> active_fe_indices;
1476
1477 /**
1478 * Helper object to transfer all active FE indices on
1479 * parallel::distributed::Triangulation objects during
1480 * refinement/coarsening and serialization.
1481 */
1482 std::unique_ptr<
1483 parallel::distributed::
1484 CellDataTransfer<dim, spacedim, std::vector<types::fe_index>>>
1485 cell_data_transfer;
1486 };
1487
1488 /**
1489 * An object containing information on the block structure.
1490 */
1491 BlockInfo block_info_object;
1492
1493 /**
1494 * Boolean indicating whether or not the current DoFHandler has
1495 * hp-capabilities.
1496 */
1497 bool hp_capability_enabled;
1498
1499 /**
1500 * Address of the triangulation to work on.
1501 */
1502 ObserverPointer<const Triangulation<dim, spacedim>, DoFHandler<dim, spacedim>>
1503 tria;
1504
1505 /**
1506 * Store a hp::FECollection object. If only a single FiniteElement is
1507 * used during initialization of this object, it contains the (one)
1508 * FiniteElement.
1509 */
1510 hp::FECollection<dim, spacedim> fe_collection;
1511
1512 /**
1513 * An object that describes how degrees of freedom should be distributed and
1514 * renumbered.
1515 */
1516 std::unique_ptr<dealii::internal::DoFHandlerImplementation::Policy::
1517 PolicyBase<dim, spacedim>>
1518 policy;
1519
1520 /**
1521 * A structure that contains all sorts of numbers that characterize the
1522 * degrees of freedom this object works on.
1523 *
1524 * For most members of this structure, there is an accessor function in this
1525 * class that returns its value.
1526 */
1527 dealii::internal::DoFHandlerImplementation::NumberCache number_cache;
1528
1529 /**
1530 * Data structure like number_cache, but for each multigrid level.
1531 */
1532 std::vector<dealii::internal::DoFHandlerImplementation::NumberCache>
1533 mg_number_cache;
1534
1535 /**
1536 * Indices of degree of freedom of each d+1 geometric object (3d: vertex,
1537 * line, quad, hex) for all relevant active finite elements. Identification
1538 * of the appropriate position is done via object_dof_ptr (CRS scheme).
1539 */
1540 mutable std::vector<std::array<std::vector<types::global_dof_index>, dim + 1>>
1541 object_dof_indices;
1542
1543 /**
1544 * Pointer to the first cached degree of freedom of a geometric object for all
1545 * relevant active finite elements.
1546 *
1547 * @note In normal mode it is possible to access this data structure directly.
1548 * In hp-mode, an indirection via hp_object_fe_indices/hp_object_fe_ptr is
1549 * necessary.
1550 */
1551 mutable std::vector<std::array<std::vector<offset_type>, dim + 1>>
1552 object_dof_ptr;
1553
1554 /**
1555 * Active FE indices of each geometric object. Identification
1556 * of the appropriate position of a cell in the vectors is done via
1557 * hp_object_fe_ptr (CRS scheme).
1558 */
1559 mutable std::array<std::vector<types::fe_index>, dim + 1>
1560 hp_object_fe_indices;
1561
1562 /**
1563 * Pointer to the first FE index of a geometric object.
1564 */
1565 mutable std::array<std::vector<offset_type>, dim + 1> hp_object_fe_ptr;
1566
1567 /**
1568 * Active FE index of an active cell (identified by level and level index).
1569 * This vector is only used in hp-mode.
1570 */
1571 mutable std::vector<std::vector<types::fe_index>> hp_cell_active_fe_indices;
1572
1573 /**
1574 * Future FE index of an active cell (identified by level and level index).
1575 * This vector is only used in hp-mode.
1576 */
1577 mutable std::vector<std::vector<types::fe_index>> hp_cell_future_fe_indices;
1578
1579 /**
1580 * An array to store the indices for level degrees of freedom located at
1581 * vertices.
1582 */
1583 std::vector<MGVertexDoFs> mg_vertex_dofs;
1584
1585 /**
1586 * Space to store the DoF numbers for the different multigrid levels.
1587 */
1588 std::vector<
1589 std::unique_ptr<dealii::internal::DoFHandlerImplementation::DoFLevel<dim>>>
1590 mg_levels;
1591
1592 /**
1593 * Space to store DoF numbers of faces in the multigrid context.
1594 */
1595 std::unique_ptr<dealii::internal::DoFHandlerImplementation::DoFFaces<dim>>
1596 mg_faces;
1597
1598 /**
1599 * We embed our data structure into a pointer to control that
1600 * all transfer related data only exists during the actual transfer process.
1601 */
1602 std::unique_ptr<ActiveFEIndexTransfer> active_fe_index_transfer;
1603
1604 /**
1605 * A list of connections with which this object connects to the
1606 * triangulation to get information about when the triangulation changes.
1607 */
1608 std::vector<boost::signals2::connection> tria_listeners;
1609
1610 /**
1611 * A list of connections with which this object connects to the
1612 * triangulation. They get triggered specifically when data needs to be
1613 * transferred due to refinement or repartitioning. Only active in hp-mode.
1614 */
1615 std::vector<boost::signals2::connection> tria_listeners_for_transfer;
1616
1617 /**
1618 * Free all memory used for non-multigrid data structures.
1619 */
1620 void
1621 clear_space();
1622
1623 /**
1624 * Free all memory used for multigrid data structures.
1625 */
1626 void
1627 clear_mg_space();
1628
1629 /**
1630 * Set up DoFHandler policy.
1631 */
1632 void
1633 setup_policy();
1634
1635 /**
1636 * Set up connections to signals of the underlying triangulation.
1637 */
1638 void
1639 connect_to_triangulation_signals();
1640
1641 /**
1642 * Create default tables for the active and future fe_indices.
1643 *
1644 * Active indices are initialized with a zero indicator, meaning that fe[0] is
1645 * going to be used by default. Future indices are initialized with an invalid
1646 * indicator, meaning that no p-adaptation is scheduled by default.
1647 *
1648 * This method is called upon construction and whenever the underlying
1649 * triangulation gets created. This ensures that each cell has a valid active
1650 * and future fe_index.
1651 */
1652 void
1653 create_active_fe_table();
1654
1655 /**
1656 * Update tables for active and future fe_indices.
1657 *
1658 * Whenever the underlying triangulation changes (either by adaptation or
1659 * deserialization), active and future FE index tables will be adjusted to the
1660 * current structure of the triangulation. Missing values of active and future
1661 * indices will be initialized with their defaults (see
1662 * create_active_fe_table()).
1663 *
1664 * This method is called post refinement and post deserialization. This
1665 * ensures that each cell has a valid active and future fe_index.
1666 */
1667 void
1668 update_active_fe_table();
1669
1670 /**
1671 * A function that will be triggered through a triangulation
1672 * signal just before the associated Triangulation or
1673 * parallel::shared::Triangulation is modified.
1674 *
1675 * The function that stores the active FE indices of all cells that will
1676 * be refined or coarsened before the refinement happens, so that
1677 * they can be set again after refinement.
1678 */
1679 void
1680 pre_transfer_action();
1681
1682 /**
1683 * A function that will be triggered through a triangulation
1684 * signal just after the associated Triangulation or
1685 * parallel::shared::Triangulation is modified.
1686 *
1687 * The function that restores the active FE indices of all cells that
1688 * were refined or coarsened.
1689 */
1690 void
1691 post_transfer_action();
1692
1693 /**
1694 * A function that will be triggered through a triangulation
1695 * signal just before the associated parallel::distributed::Triangulation is
1696 * modified.
1697 *
1698 * The function that stores all active FE indices on locally owned cells for
1699 * distribution over all participating processors.
1700 */
1701 void
1702 pre_distributed_transfer_action();
1703
1704 /**
1705 * A function that will be triggered through a triangulation
1706 * signal just after the associated parallel::distributed::Triangulation is
1707 * modified.
1708 *
1709 * The function that restores all active FE indices on locally owned cells
1710 * that have been communicated.
1711 */
1712 void
1713 post_distributed_transfer_action();
1714
1715
1716 // Make accessor objects friends.
1717 template <int, int, int, bool>
1718 friend class dealii::DoFAccessor;
1719 template <int, int, bool>
1720 friend class dealii::DoFCellAccessor;
1721 friend struct dealii::internal::DoFAccessorImplementation::Implementation;
1722 friend struct dealii::internal::DoFCellAccessorImplementation::Implementation;
1723
1724 // Likewise for DoFLevel objects since they need to access the vertex dofs
1725 // in the functions that set and retrieve vertex dof indices.
1726 friend struct dealii::internal::DoFHandlerImplementation::Implementation;
1727 friend struct dealii::internal::hp::DoFHandlerImplementation::Implementation;
1728 friend struct dealii::internal::DoFHandlerImplementation::Policy::
1729 Implementation;
1730
1731 // explicitly check for sensible template arguments, but not on windows
1732 // because MSVC creates bogus warnings during normal compilation
1733 #ifndef DEAL_II_MSVC
1734 static_assert(dim <= spacedim,
1735 "The dimension <dim> of a DoFHandler must be less than or "
1736 "equal to the space dimension <spacedim> in which it lives.");
1737 #endif
1738 };
1739
1740 namespace internal
1741 {
1742 namespace hp
1743 {
1744 namespace DoFHandlerImplementation
1745 {
1746 /**
1747 * Given a DoFHandler object in hp-mode, make sure that the
1748 * future FE indices that a user has set for locally owned cells are
1749 * communicated to all other relevant cells as well.
1750 *
1751 * For parallel::shared::Triangulation objects,
1752 * this information is distributed on both ghost and artificial cells.
1753 *
1754 * In case a parallel::distributed::Triangulation is used,
1755 * indices are communicated only to ghost cells.
1756 */
1757 template <int dim, int spacedim>
1758 void
1759 communicate_future_fe_indices(DoFHandler<dim, spacedim> &dof_handler);
1760
1761 /**
1762 * Return the index of the finite element from the entire hp::FECollection
1763 * that is dominated by those assigned as future finite elements to the
1764 * children of @p parent.
1765 *
1766 * We find the corresponding finite element among the future finite
1767 * elements on the children of this cell. If none of them qualify, we
1768 * extend our search on the whole hp::FECollection, which is the element
1769 * that describes the smallest finite element space that includes all
1770 * future finite elements assigned to the children. If the function is not
1771 * able to find a finite element at all, an assertion will be triggered.
1772 *
1773 * In this way, we determine the finite element of the parent cell in case
1774 * of h-coarsening in the hp-context.
1775 *
1776 * @note This function can only be called on direct parent cells, i.e.,
1777 * non-active cells whose children are all active.
1778 *
1779 * @note On parallel Triangulation objects where sibling cells
1780 * can be ghost cells, make sure that future FE indices have been properly
1781 * communicated with communicate_future_fe_indices() first. Otherwise,
1782 * results might differ on different processors. There is no check for
1783 * consistency of future FE indices.
1784 */
1785 template <int dim, int spacedim = dim>
1786 unsigned int
1787 dominated_future_fe_on_children(
1788 const typename DoFHandler<dim, spacedim>::cell_iterator &parent);
1789
1790 /**
1791 * Exception
1792 */
1793 DeclExceptionMsg(
1794 ExcNoDominatedFiniteElementOnChildren,
1795 "No FiniteElement has been found in your FECollection that is "
1796 "dominated by all children of a cell you are trying to coarsen!");
1797 } // namespace DoFHandlerImplementation
1798 } // namespace hp
1799 } // namespace internal
1800
1801 #ifndef DOXYGEN
1802
1803 /* ----------------------- Inline functions ----------------------------------
1804 */
1805
1806
1807 template <int dim, int spacedim>
1808 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1809 inline bool DoFHandler<dim, spacedim>::has_hp_capabilities() const
1810 {
1811 return hp_capability_enabled;
1812 }
1813
1814
1815
1816 template <int dim, int spacedim>
1817 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1818 inline bool DoFHandler<dim, spacedim>::has_level_dofs() const
1819 {
1820 return mg_number_cache.size() > 0;
1821 }
1822
1823
1824
1825 template <int dim, int spacedim>
1826 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1827 inline bool DoFHandler<dim, spacedim>::has_active_dofs() const
1828 {
1829 return number_cache.n_global_dofs > 0;
1830 }
1831
1832
1833
1834 template <int dim, int spacedim>
1835 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1836 inline types::global_dof_index DoFHandler<dim, spacedim>::n_dofs() const
1837 {
1838 return number_cache.n_global_dofs;
1839 }
1840
1841
1842
1843 template <int dim, int spacedim>
1844 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1845 inline types::global_dof_index
1846 DoFHandler<dim, spacedim>::n_dofs(const unsigned int level) const
1847 {
1848 Assert(has_level_dofs(),
1849 ExcMessage(
1850 "n_dofs(level) can only be called after distribute_mg_dofs()"));
1851 Assert(level < mg_number_cache.size(), ExcInvalidLevel(level));
1852 return mg_number_cache[level].n_global_dofs;
1853 }
1854
1855
1856
1857 template <int dim, int spacedim>
1858 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1859 types::global_dof_index DoFHandler<dim, spacedim>::n_locally_owned_dofs() const
1860 {
1861 return number_cache.n_locally_owned_dofs;
1862 }
1863
1864
1865
1866 template <int dim, int spacedim>
1867 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1868 const IndexSet &DoFHandler<dim, spacedim>::locally_owned_dofs() const
1869 {
1870 return number_cache.locally_owned_dofs;
1871 }
1872
1873
1874
1875 template <int dim, int spacedim>
1876 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1877 const IndexSet &DoFHandler<dim, spacedim>::locally_owned_mg_dofs(
1878 const unsigned int level) const
1879 {
1880 Assert(level < this->get_triangulation().n_global_levels(),
1881 ExcMessage("The given level index exceeds the number of levels "
1882 "present in the triangulation"));
1883 Assert(
1884 mg_number_cache.size() == this->get_triangulation().n_global_levels(),
1885 ExcMessage(
1886 "The level dofs are not set up properly! Did you call distribute_mg_dofs()?"));
1887 return mg_number_cache[level].locally_owned_dofs;
1888 }
1889
1890
1891
1892 template <int dim, int spacedim>
1893 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1894 inline const FiniteElement<dim, spacedim> &DoFHandler<dim, spacedim>::get_fe(
1895 const types::fe_index number) const
1896 {
1897 Assert(fe_collection.size() > 0,
1898 ExcMessage("No finite element collection is associated with "
1899 "this DoFHandler"));
1900 return fe_collection[number];
1901 }
1902
1903
1904
1905 template <int dim, int spacedim>
1906 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1907 inline const hp::FECollection<dim, spacedim>
1908 &DoFHandler<dim, spacedim>::get_fe_collection() const
1909 {
1910 return fe_collection;
1911 }
1912
1913
1914
1915 template <int dim, int spacedim>
1916 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1917 inline const Triangulation<dim, spacedim>
1918 &DoFHandler<dim, spacedim>::get_triangulation() const
1919 {
1920 Assert(tria != nullptr,
1921 ExcMessage("This DoFHandler object has not been associated "
1922 "with a triangulation."));
1923 return *tria;
1924 }
1925
1926
1927
1928 template <int dim, int spacedim>
1929 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1930 inline MPI_Comm DoFHandler<dim, spacedim>::get_mpi_communicator() const
1931 {
1932 Assert(tria != nullptr,
1933 ExcMessage("This DoFHandler object has not been associated "
1934 "with a triangulation."));
1935 return tria->get_mpi_communicator();
1936 }
1937
1938
1939
1940 template <int dim, int spacedim>
1941 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1942 inline MPI_Comm DoFHandler<dim, spacedim>::get_communicator() const
1943 {
1944 return get_mpi_communicator();
1945 }
1946
1947
1948
1949 template <int dim, int spacedim>
1950 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1951 inline const BlockInfo &DoFHandler<dim, spacedim>::block_info() const
1952 {
1953 Assert(this->hp_capability_enabled == false, ExcNotImplementedWithHP());
1954
1955 return block_info_object;
1956 }
1957
1958
1959
1960 template <int dim, int spacedim>
1961 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1962 template <typename number>
1963 types::global_dof_index DoFHandler<dim, spacedim>::n_boundary_dofs(
1964 const std::map<types::boundary_id, const Function<spacedim, number> *>
1965 &boundary_ids) const
1966 {
1967 Assert(!(dim == 2 && spacedim == 3) || this->hp_capability_enabled == false,
1968 ExcNotImplementedWithHP());
1969
1970 // extract the set of boundary ids and forget about the function object
1971 // pointers
1972 std::set<types::boundary_id> boundary_ids_only;
1973 for (typename std::map<types::boundary_id,
1974 const Function<spacedim, number> *>::const_iterator p =
1975 boundary_ids.begin();
1976 p != boundary_ids.end();
1977 ++p)
1978 boundary_ids_only.insert(p->first);
1979
1980 // then just hand everything over to the other function that does the work
1981 return n_boundary_dofs(boundary_ids_only);
1982 }
1983
1984
1985
1986 namespace internal
1987 {
1988 /**
1989 * Return a string representing the dynamic type of the given argument.
1990 * This is basically the same what typeid(...).name() does, but it turns out
1991 * this is broken on Intel 13+.
1992 *
1993 * Defined in dof_handler.cc.
1994 */
1995 template <int dim, int spacedim>
1996 std::string
1997 policy_to_string(const dealii::internal::DoFHandlerImplementation::Policy::
1998 PolicyBase<dim, spacedim> &policy);
1999 } // namespace internal
2000
2001
2002
2003 template <int dim, int spacedim>
2004 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
2005 template <class Archive>
2006 void DoFHandler<dim, spacedim>::save(Archive &ar, const unsigned int) const
2007 {
2008 if (this->hp_capability_enabled)
2009 {
2010 ar &this->object_dof_indices;
2011 ar &this->object_dof_ptr;
2012
2013 ar &this->hp_cell_active_fe_indices;
2014 ar &this->hp_cell_future_fe_indices;
2015
2016 ar &hp_object_fe_ptr;
2017 ar &hp_object_fe_indices;
2018
2019 ar &number_cache;
2020
2021 ar &mg_number_cache;
2022
2023 // write out the number of triangulation cells and later check during
2024 // loading that this number is indeed correct; same with something that
2025 // identifies the policy
2026 const unsigned int n_cells = this->tria->n_cells();
2027 std::string policy_name =
2028 dealii::internal::policy_to_string(*this->policy);
2029
2030 ar &n_cells &policy_name;
2031 }
2032 else
2033 {
2034 ar &this->block_info_object;
2035 ar &number_cache;
2036
2037 ar &this->object_dof_indices;
2038 ar &this->object_dof_ptr;
2039
2040 // write out the number of triangulation cells and later check during
2041 // loading that this number is indeed correct; same with something that
2042 // identifies the FE and the policy
2043 unsigned int n_cells = this->tria->n_cells();
2044 std::string fe_name = this->get_fe(0).get_name();
2045 std::string policy_name = internal::policy_to_string(*this->policy);
2046
2047 ar &n_cells &fe_name &policy_name;
2048 }
2049 }
2050
2051
2052
2053 template <int dim, int spacedim>
2054 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
2055 template <class Archive>
2056 void DoFHandler<dim, spacedim>::load(Archive &ar, const unsigned int)
2057 {
2058 if (this->hp_capability_enabled)
2059 {
2060 ar &this->object_dof_indices;
2061 ar &this->object_dof_ptr;
2062
2063 ar &this->hp_cell_active_fe_indices;
2064 ar &this->hp_cell_future_fe_indices;
2065
2066 ar &hp_object_fe_ptr;
2067 ar &hp_object_fe_indices;
2068
2069 ar &number_cache;
2070
2071 ar &mg_number_cache;
2072
2073 // these are the checks that correspond to the last block in the save()
2074 // function
2075 unsigned int n_cells;
2076 std::string policy_name;
2077
2078 ar &n_cells &policy_name;
2079
2080 AssertThrow(
2081 n_cells == this->tria->n_cells(),
2082 ExcMessage(
2083 "The object being loaded into does not match the triangulation "
2084 "that has been stored previously."));
2085 AssertThrow(
2086 policy_name == dealii::internal::policy_to_string(*this->policy),
2087 ExcMessage("The policy currently associated with this DoFHandler (" +
2088 dealii::internal::policy_to_string(*this->policy) +
2089 ") does not match the one that was associated with the "
2090 "DoFHandler previously stored (" +
2091 policy_name + ")."));
2092 }
2093 else
2094 {
2095 ar &this->block_info_object;
2096 ar &number_cache;
2097
2098 object_dof_indices.clear();
2099
2100 object_dof_ptr.clear();
2101
2102 ar &this->object_dof_indices;
2103 ar &this->object_dof_ptr;
2104
2105 // these are the checks that correspond to the last block in the save()
2106 // function
2107 unsigned int n_cells;
2108 std::string fe_name;
2109 std::string policy_name;
2110
2111 ar &n_cells &fe_name &policy_name;
2112
2113 AssertThrow(
2114 n_cells == this->tria->n_cells(),
2115 ExcMessage(
2116 "The object being loaded into does not match the triangulation "
2117 "that has been stored previously."));
2118 AssertThrow(
2119 fe_name == this->get_fe(0).get_name(),
2120 ExcMessage(
2121 "The finite element associated with this DoFHandler does not match "
2122 "the one that was associated with the DoFHandler previously stored."));
2123 AssertThrow(policy_name == internal::policy_to_string(*this->policy),
2124 ExcMessage(
2125 "The policy currently associated with this DoFHandler (" +
2126 internal::policy_to_string(*this->policy) +
2127 ") does not match the one that was associated with the "
2128 "DoFHandler previously stored (" +
2129 policy_name + ")."));
2130 }
2131 }
2132
2133
2134
2135 template <int dim, int spacedim>
2136 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
2137 inline types::global_dof_index
2138 &DoFHandler<dim, spacedim>::MGVertexDoFs::access_index(
2139 const unsigned int level,
2140 const unsigned int dof_number,
2141 const unsigned int dofs_per_vertex)
2142 {
2143 Assert((level >= coarsest_level) && (level <= finest_level),
2144 ExcInvalidLevel(level));
2145 return indices[dofs_per_vertex * (level - coarsest_level) + dof_number];
2146 }
2147
2148
2149
2150 // Declare the existence of explicit instantiations of the class
2151 // above. This is not strictly necessary, but tells the compiler to
2152 // avoid instantiating templates that we know are instantiated in
2153 // .cc files and so can be referenced without implicit
2154 // instantiations.
2155 //
2156 // Unfortunately, this does not seem to work when building modules
2157 // because the compiler (well, Clang at least) then just doesn't
2158 // instantiate these classes at all, even though their members are
2159 // defined and explicitly instantiated in a .cc file.
2160 # ifndef DEAL_II_BUILDING_CXX20_MODULE
2161 extern template class DoFHandler<1, 1>;
2162 extern template class DoFHandler<1, 2>;
2163 extern template class DoFHandler<1, 3>;
2164 extern template class DoFHandler<2, 2>;
2165 extern template class DoFHandler<2, 3>;
2166 extern template class DoFHandler<3, 3>;
2167 # endif
2168
2169 #endif // DOXYGEN
2170
2171 DEAL_II_NAMESPACE_CLOSE
2172
2173 #endif