Debian Codegraph @

include/deal.II/dofs/dof_accessor.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_accessor_h
16 #define dealii_dof_accessor_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/types.h>
22
23 #include <deal.II/dofs/dof_faces.h>
24 #include <deal.II/dofs/dof_iterator_selector.h>
25 #include <deal.II/dofs/dof_levels.h>
26
27 #include <deal.II/grid/tria_accessor.h>
28
29 #include <deal.II/lac/affine_constraints.h>
30 #include <deal.II/lac/read_vector.h>
31 #include <deal.II/lac/read_write_vector.h>
32
33 #include <boost/container/small_vector.hpp>
34
35 #include <limits>
36 #include <set>
37 #include <type_traits>
38 #include <vector>
39
40
41 DEAL_II_NAMESPACE_OPEN
42
43 // Forward declarations
44 #ifndef DOXYGEN
45 template <typename number>
46 class FullMatrix;
47 template <typename number>
48 class Vector;
49 template <typename number>
50 class AffineConstraints;
51
52 template <typename Accessor>
53 class TriaRawIterator;
54
55 template <int, int>
56 class FiniteElement;
57
58 namespace internal
59 {
60 namespace DoFCellAccessorImplementation
61 {
62 struct Implementation;
63 }
64
65 namespace DoFHandlerImplementation
66 {
67 struct Implementation;
68 namespace Policy
69 {
70 struct Implementation;
71 }
72 } // namespace DoFHandlerImplementation
73
74 namespace hp
75 {
76 namespace DoFHandlerImplementation
77 {
78 struct Implementation;
79 }
80 } // namespace hp
81 } // namespace internal
82 #endif
83
84
85 namespace internal
86 {
87 namespace DoFAccessorImplementation
88 {
89 /**
90 * This is a switch class which only declares an @p alias. It is meant to
91 * determine which class a DoFAccessor class is to be derived from. By
92 * default, <tt>DoFAccessor@<structdim,dim,spacedim@></tt> derives from
93 * the alias in the general
94 * <tt>Inheritance@<structdim,dim,spacedim@></tt> class, which is
95 * <tt>TriaAccessor@<structdim,dim,spacedim@></tt>, but if
96 * <tt>structdim==dim</tt>, then the specialization
97 * <tt>Inheritance@<dim,dim,spacedim@></tt> is used which declares its
98 * local type to be <tt>CellAccessor@<dim,spacedim@></tt>. Therefore, the
99 * inheritance is automatically chosen to be from CellAccessor if the
100 * object under consideration has full dimension, i.e. constitutes a cell.
101 *
102 * @ingroup dofs
103 * @ingroup Accessors
104 */
105 template <int structdim, int dim, int spacedim>
106 struct Inheritance
107 {
108 /**
109 * Declaration of the @p alias. See the full documentation for more
110 * information.
111 */
112 using BaseClass = dealii::TriaAccessor<structdim, dim, spacedim>;
113 };
114
115
116 /**
117 * This is the specialization of the general template used for the case
118 * where an object has full dimension, i.e. is a cell. See the general
119 * template for more details.
120 */
121 template <int dim, int spacedim>
122 struct Inheritance<dim, dim, spacedim>
123 {
124 /**
125 * Declaration of the @p alias. See the full documentation for more
126 * information.
127 */
128 using BaseClass = dealii::CellAccessor<dim, spacedim>;
129 };
130
131 struct Implementation;
132 } // namespace DoFAccessorImplementation
133 } // namespace internal
134
135
136 /* -------------------------------------------------------------------------- */
137
138
139
140 /**
141 * A class that gives access to the degrees of freedom stored in a DoFHandler
142 * object. Accessors are used to access the data that pertains to edges,
143 * faces, and cells of a triangulation. The concept is explained in more
144 * detail in connection to
145 * @ref Iterators.
146 *
147 * This class follows mainly the route laid out by the accessor library
148 * declared in the triangulation library (TriaAccessor). It enables the user
149 * to access the degrees of freedom on lines, quads, or hexes. The first
150 * template argument of this class determines the dimensionality of the object
151 * under consideration: 1 for lines, 2 for quads, and 3 for hexes. The second
152 * argument denotes the type of DoFHandler we should work on. From the second
153 * template argument we also deduce the dimension of the Triangulation this
154 * object refers to as well as the dimension of the space into which it is
155 * embedded. Finally, the template argument <code>level_dof_access</code>
156 * governs the behavior of the function get_active_or_mg_dof_indices(). See
157 * the section on Generic loops below.
158 *
159 * <h3>Alias</h3>
160 *
161 * Usage is best to happen through the alias to the various kinds of iterators
162 * provided by the DoFHandler class, since they are more secure to changes in
163 * the class naming and template interface as well as providing easier typing
164 * (much less complicated names!).
165 *
166 * <h3>Generic loops and the third template argument</h3>
167 *
168 * Many loops look very similar, whether they operate on the active dofs of
169 * the active cells of the Triangulation or on the level dofs of a single
170 * level or the whole grid hierarchy. In order to use polymorphism in such
171 * loops, they access degrees of freedom through the function
172 * get_active_or_mg_dof_indices(), which changes behavior according to the
173 * third template argument. If the argument is false, then the active dofs of
174 * active cells are accessed. If it is true, the level dofs are used.
175 * DoFHandler has functions, for instance begin() and begin_mg(), which return
176 * either type or the other. Additionally, they can be cast into each other,
177 * in case this is needed, since they access the same data.
178 *
179 * It is recommended to use the function get_active_or_mg_dof_indices()
180 * in generic loops in lieu of get_dof_indices() or get_mg_dof_indices().
181 *
182 * <h3>Inheritance</h3>
183 *
184 * If the structural dimension given by the first template argument equals the
185 * dimension of the DoFHandler (given as the second template argument), then
186 * we are obviously dealing with cells, rather than lower-dimensional objects.
187 * In that case, inheritance is from CellAccessor, to provide access to all
188 * the cell specific information afforded by that class. Otherwise, i.e. for
189 * lower-dimensional objects, inheritance is from TriaAccessor.
190 *
191 * There is a DoFCellAccessor class that provides the equivalent to the
192 * CellAccessor class.
193 *
194 * @tparam structdim The dimensionality of the objects the accessor
195 * represents. For example, points have @p structdim equal to zero,
196 * edges have @p structdim equal to one, etc.
197 * @tparam dim Dimension of the underlying DoFHandler.
198 * @tparam spacedim Space dimension of the underlying DoFHandler.
199 * @tparam level_dof_access If @p false, then the accessor simply represents
200 * a cell, face, or edge in a DoFHandler for which degrees of freedom only
201 * exist on the finest level. Some operations are not allowed in this case,
202 * such as asking for DoF indices on non-active cells. On the other hand,
203 * if this template argument is @p true, then the accessor represents an
204 * object in a multilevel hierarchy of degrees of freedom. In this case,
205 * accessing DoF indices of <i>any</i> cell is possible, and will return
206 * the <i>level</i> indices (which, for active cells, may be different
207 * from the <i>global</i> indices).
208 *
209 * @ingroup dofs
210 * @ingroup Accessors
211 */
212 template <int structdim, int dim, int spacedim, bool level_dof_access>
213 class DoFAccessor : public dealii::internal::DoFAccessorImplementation::
214 Inheritance<structdim, dim, spacedim>::BaseClass
215 {
216 public:
217 /**
218 * A static variable that allows users of this class to discover the value
219 * of the second template argument.
220 */
221 static constexpr unsigned int dimension = dim;
222
223 /**
224 * A static variable that allows users of this class to discover the value
225 * of the third template argument.
226 */
227 static constexpr unsigned int space_dimension = spacedim;
228
229 /**
230 * Declare an alias to the base class to make accessing some of the
231 * exception classes simpler.
232 */
233 using BaseClass = typename dealii::internal::DoFAccessorImplementation::
234 Inheritance<structdim, dimension, space_dimension>::BaseClass;
235
236 /**
237 * Data type passed by the iterator class.
238 */
239 using AccessorData = DoFHandler<dimension, space_dimension>;
240
241 /**
242 * @name Constructors
243 */
244 /**
245 * @{
246 */
247
248 /**
249 * Default constructor. Provides an accessor that can't be used.
250 */
251 DoFAccessor();
252
253 /**
254 * Constructor that generates an access that points to a particular cell or
255 * face or edge in a DoFHandler.
256 *
257 * @param tria The triangulation into which this accessor points.
258 * @param level The level within the mesh hierarchy of the object pointed
259 * to. For example, coarse mesh cells will have level zero, their children
260 * level one, and so on. This argument is ignored for faces and edges
261 * which do not have a level.
262 * @param index The index of the object pointed to within the specified
263 * refinement level.
264 * @param dof_handler A pointer to the DoFHandler object to which the
265 * accessor shall refer. This DoFHandler object must of course be built on
266 * the same triangulation as the one specified in the first argument.
267 */
268 DoFAccessor(const Triangulation<dim, spacedim> *tria,
269 const int level,
270 const int index,
271 const DoFHandler<dim, spacedim> *dof_handler);
272
273 /**
274 * Copy constructor.
275 */
276 DoFAccessor(const DoFAccessor<structdim, dim, spacedim, level_dof_access> &) =
277 default;
278
279 /**
280 * Move constructor.
281 */
282 DoFAccessor( // NOLINT
283 DoFAccessor<structdim, dim, spacedim, level_dof_access> &&) = // NOLINT
284 default; // NOLINT
285
286 /**
287 * Destructor.
288 */
289 ~DoFAccessor() = default;
290
291 /**
292 * Conversion constructor. This constructor exists to make certain
293 * constructs simpler to write in dimension independent code. For example,
294 * it allows assigning a face iterator to a line iterator, an operation that
295 * is useful in 2d but doesn't make any sense in 3d. The constructor here
296 * exists for the purpose of making the code conform to C++ but it will
297 * unconditionally abort; in other words, assigning a face iterator to a
298 * line iterator is better put into an if-statement that checks that the
299 * dimension is two, and assign to a quad iterator in 3d (an operator that,
300 * without this constructor would be illegal if we happen to compile for
301 * 2d).
302 */
303 template <int structdim2, int dim2, int spacedim2>
304 DoFAccessor(const InvalidAccessor<structdim2, dim2, spacedim2> &);
305
306 /**
307 * Another conversion operator between objects that don't make sense, just
308 * like the previous one.
309 */
310 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
311 DoFAccessor(
312 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &);
313
314 /**
315 * Copy constructor allowing to switch level access and active access.
316 */
317 template <bool level_dof_access2>
318 DoFAccessor(const DoFAccessor<structdim, dim, spacedim, level_dof_access2> &);
319
320 /**
321 * Copy operator. These operators are usually used in a context like
322 * <tt>iterator a,b; *a=*b;</tt>. Presumably, the intent here is to copy the
323 * object pointed to
324 * by @p b to the object pointed to by @p a. However, the result of
325 * dereferencing an iterator is not an object but an accessor; consequently,
326 * this operation is not useful for iterators on DoF handler objects.
327 * Consequently, this operator is declared as deleted and can not be used.
328 */
329 DoFAccessor<structdim, dim, spacedim, level_dof_access> &
330 operator=(const DoFAccessor<structdim, dim, spacedim, level_dof_access> &da) =
331 delete;
332
333 /**
334 * Move assignment operator.
335 */
336 DoFAccessor<structdim, dim, spacedim, level_dof_access> & // NOLINT
337 operator=( // NOLINT
338 DoFAccessor<structdim, dim, spacedim, level_dof_access> &&) = // NOLINT
339 default; // NOLINT
340
341 /**
342 * @}
343 */
344
345 /**
346 * Return a handle on the DoFHandler object which we are using.
347 */
348 const DoFHandler<dim, spacedim> &
349 get_dof_handler() const;
350
351 /**
352 * Implement the copy operator needed for the iterator classes.
353 */
354 template <bool level_dof_access2>
355 void
356 copy_from(const DoFAccessor<structdim, dim, spacedim, level_dof_access2> &a);
357
358 /**
359 * Copy operator used by the iterator class. Keeps the previously set dof
360 * handler, but sets the object coordinates of the TriaAccessor.
361 */
362 void
363 copy_from(const TriaAccessorBase<structdim, dim, spacedim> &da);
364
365 /**
366 * Tell the caller whether get_active_or_mg_dof_indices() accesses active or
367 * level dofs.
368 */
369 static bool
370 is_level_cell();
371
372 /**
373 * @name Accessing sub-objects
374 */
375 /**
376 * @{
377 */
378
379 /**
380 * Return an iterator pointing to the @p c-th child.
381 */
382 TriaIterator<DoFAccessor<structdim, dim, spacedim, level_dof_access>>
383 child(const unsigned int c) const;
384
385 /**
386 * Pointer to the @p ith line bounding this object. If the current object is
387 * a line itself, then the only valid index is @p i equals to zero, and the
388 * function returns an iterator to itself.
389 */
390 typename dealii::internal::DoFHandlerImplementation::
391 Iterators<dim, spacedim, level_dof_access>::line_iterator
392 line(const unsigned int i) const;
393
394 /**
395 * Pointer to the @p ith quad bounding this object. If the current object is
396 * a quad itself, then the only valid index is @p i equals to zero, and the
397 * function returns an iterator to itself.
398 */
399 typename dealii::internal::DoFHandlerImplementation::
400 Iterators<dim, spacedim, level_dof_access>::quad_iterator
401 quad(const unsigned int i) const;
402
403 /**
404 * @}
405 */
406
407 /**
408 * @name Accessing the DoF indices of this object
409 */
410 /**
411 * @{
412 */
413
414 /**
415 * Return the <i>global</i> indices of the degrees of freedom located on
416 * this object in the standard ordering defined by the finite element (i.e.,
417 * dofs on vertex 0, dofs on vertex 1, etc, dofs on line 0, dofs on line 1,
418 * etc, dofs on quad 0, etc.) This function is only available on
419 * <i>active</i> objects (see
420 * @ref GlossActive "this glossary entry").
421 *
422 * The cells needs to be an active cell (and not artificial in a parallel
423 * distributed computation).
424 *
425 * The vector has to have the right size before being passed to this
426 * function.
427 *
428 * The last argument denotes the finite element index. For the standard
429 * ::DoFHandler class, this value must be equal to its default value since
430 * that class only supports the same finite element on all cells anyway.
431 *
432 * However, when the relevant DoFHandler object has hp-capabilities enabled,
433 * different finite element objects may be used on different cells. On faces
434 * between two cells, as well as vertices, there may therefore be two sets
435 * of degrees of freedom, one for each of the finite elements used on the
436 * adjacent cells. In order to specify which set of degrees of freedom to
437 * work on, the last argument is used to disambiguate. Finally, if this
438 * function is called for a cell object, there can only be a single set of
439 * degrees of freedom, and fe_index has to match the result of
440 * active_fe_index().
441 *
442 * For cells, there is only a single possible finite element index (namely
443 * the one for that cell, returned by <code>cell-@>active_fe_index</code>.
444 * Consequently, the derived DoFCellAccessor class has an overloaded version
445 * of this function that calls the present function with
446 * <code>cell-@>active_fe_index</code> as last argument.
447 */
448 void
449 get_dof_indices(
450 std::vector<types::global_dof_index> &dof_indices,
451 const types::fe_index fe_index = numbers::invalid_fe_index) const;
452
453 /**
454 * Return the global multilevel indices of the degrees of freedom that live
455 * on the current object with respect to the given level within the
456 * multigrid hierarchy. The indices refer to the local numbering for the
457 * level this line lives on.
458 */
459 void
460 get_mg_dof_indices(
461 const int level,
462 std::vector<types::global_dof_index> &dof_indices,
463 const types::fe_index fe_index = numbers::invalid_fe_index) const;
464
465 /**
466 * Set the level DoF indices that are returned by get_mg_dof_indices.
467 */
468 void
469 set_mg_dof_indices(
470 const int level,
471 const std::vector<types::global_dof_index> &dof_indices,
472 const types::fe_index fe_index = numbers::invalid_fe_index);
473
474 /**
475 * Global DoF index of the <i>i</i> degree associated with the @p vertexth
476 * vertex of the present cell.
477 *
478 * The last argument denotes the finite element index. For the standard
479 * ::DoFHandler class, this value must be equal to its default value since
480 * that class only supports the same finite element on all cells anyway.
481 *
482 * However, when hp-capabilities are enabled, different finite
483 * element objects may be used on different cells. On faces between
484 * two cells, as well as vertices, there may therefore be two sets
485 * of degrees of freedom, one for each of the finite elements used
486 * on the adjacent cells. In order to specify which set of degrees
487 * of freedom to work on, the last argument is used to
488 * disambiguate. Finally, if this function is called for a cell
489 * object, there can only be a single set of degrees of freedom, and
490 * `fe_index` has to match the result of
491 * `cell->active_fe_index()`. Alternatively, if `fe_index` is left
492 * to its default value when this function is called on a cell, then
493 * this is interpreted as equal to `cell->active_fe_index()`.
494 */
495 types::global_dof_index
496 vertex_dof_index(
497 const unsigned int vertex,
498 const unsigned int i,
499 const types::fe_index fe_index = numbers::invalid_fe_index) const;
500
501 /**
502 * Return the global DoF index of the <code>i</code>th degree of freedom
503 * associated with the <code>vertex</code>th vertex on level @p level. Also
504 * see vertex_dof_index().
505 */
506 types::global_dof_index
507 mg_vertex_dof_index(
508 const int level,
509 const unsigned int vertex,
510 const unsigned int i,
511 const types::fe_index fe_index = numbers::invalid_fe_index) const;
512
513 /**
514 * Index of the <i>i</i>th degree of freedom of this object.
515 *
516 * The last argument denotes the finite element index. For the standard
517 * ::DoFHandler class, this value must be equal to its default value since
518 * that class only supports the same finite element on all cells anyway.
519 *
520 * However, when hp-capabilities are enabled, different finite element
521 * objects may be used on different cells. On faces between two cells, as
522 * well as vertices, there may therefore be two sets of degrees of freedom,
523 * one for each of the finite elements used on the adjacent cells. In order
524 * to specify which set of degrees of freedom to work on, the last argument
525 * is used to disambiguate. Finally, if this function is called for a cell
526 * object, there can only be a single set of degrees of freedom, and
527 * fe_index has to match the result of active_fe_index().
528 *
529 * @note While the get_dof_indices() function returns an array that contains
530 * the indices of all degrees of freedom that somehow live on this object
531 * (i.e. on the vertices, edges or interior of this object), the current
532 * dof_index() function only considers the DoFs that really belong to this
533 * particular object's interior. In other words, as an example, if the
534 * current object refers to a quad (a cell in 2d, a face in 3d) and the
535 * finite element associated with it is a bilinear one, then the
536 * get_dof_indices() will return an array of size 4 while dof_index() will
537 * produce an exception because no degrees are defined in the interior of
538 * the face.
539 */
540 types::global_dof_index
541 dof_index(const unsigned int i,
542 const types::fe_index fe_index = numbers::invalid_fe_index) const;
543
544 /**
545 * Return the dof_index on the given level. Also see dof_index.
546 */
547 types::global_dof_index
548 mg_dof_index(const int level, const unsigned int i) const;
549
550 /**
551 * @}
552 */
553
554 /**
555 * @name Accessing the finite element associated with this object
556 */
557 /**
558 * @{
559 */
560
561 /**
562 * Return the number of finite elements that are active on a given object.
563 *
564 * When hp-capabilities are disabled the answer is, of course, always one.
565 * However, when hp-capabilities are enabled, this isn't the case: If this
566 * is a cell, the answer is of course one. If it is a face, the answer may
567 * be one or two, depending on whether the two adjacent cells use the same
568 * finite element or not. If it is an edge in 3d, the possible return value
569 * may be one or any other value larger than that.
570 */
571 unsigned int
572 n_active_fe_indices() const;
573
574 /**
575 * Return the @p n-th active FE index on this object. For cells and all
576 * non-hp-objects, there is only a single active FE index, so the argument
577 * must be equal to zero. For lower-dimensional hp-objects, there are
578 * n_active_fe_indices() active finite elements, and this function can be
579 * queried for their indices.
580 */
581 types::fe_index
582 nth_active_fe_index(const unsigned int n) const;
583
584 /**
585 * Returns all active FE indices on this object.
586 *
587 * The size of the returned set equals the number of finite elements that
588 * are active on this object.
589 */
590 std::set<types::fe_index>
591 get_active_fe_indices() const;
592
593 /**
594 * Return true if the finite element with given index is active on the
595 * present object. When the current DoFHandler does not have
596 * hp-capabilities, this is of course the case only if @p fe_index equals
597 * zero. For cells, it is the case if @p fe_index equals active_fe_index()
598 * of this cell. For faces and other lower- dimensional objects, there may
599 * be more than one @p fe_index that are active on any given object (see
600 * n_active_fe_indices()).
601 */
602 bool
603 fe_index_is_active(const types::fe_index fe_index) const;
604
605 /**
606 * Return a reference to the finite element used on this object with the
607 * given @p fe_index. @p fe_index must be used on this object, i.e.
608 * <code>fe_index_is_active(fe_index)</code> must return true.
609 */
610 const FiniteElement<dim, spacedim> &
611 get_fe(const types::fe_index fe_index) const;
612
613 /**
614 * @}
615 */
616
617 /**
618 * Exceptions for child classes
619 *
620 * @ingroup Exceptions
621 */
622 DeclExceptionMsg(ExcInvalidObject,
623 "This accessor object has not been "
624 "associated with any DoFHandler object.");
625 /**
626 * Exception
627 *
628 * @ingroup Exceptions
629 */
630 DeclException0(ExcVectorNotEmpty);
631 /**
632 * Exception
633 *
634 * @ingroup Exceptions
635 */
636 DeclException0(ExcVectorDoesNotMatch);
637 /**
638 * Exception
639 *
640 * @ingroup Exceptions
641 */
642 DeclException0(ExcMatrixDoesNotMatch);
643 /**
644 * A function has been called for a cell which should be
645 * @ref GlossActive "active",
646 * but is refined.
647 *
648 * @ingroup Exceptions
649 */
650 DeclException0(ExcNotActive);
651 /**
652 * Exception
653 *
654 * @ingroup Exceptions
655 */
656 DeclException0(ExcCantCompareIterators);
657
658 protected:
659 /**
660 * Store the address of the DoFHandler object to be accessed.
661 */
662 DoFHandler<dim, spacedim> *dof_handler;
663
664 public:
665 /**
666 * Compare for equality. Return <tt>true</tt> if the two accessors refer to
667 * the same object.
668 *
669 * The template parameters of this function allow for a comparison of very
670 * different objects. Therefore, some of them are disabled. Namely, if the
671 * dimension, or the dof handler of the two objects differ, an exception is
672 * generated. It can be expected that this is an unwanted comparison.
673 *
674 * The template parameter <tt>level_dof_access2</tt> is ignored, such that
675 * an iterator with level access can be equal to one with access to the
676 * active degrees of freedom.
677 */
678 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
679 bool
680 operator==(
681 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
682
683 /**
684 * Compare for inequality. The boolean not of operator==().
685 */
686 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
687 bool
688 operator!=(
689 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
690
691 protected:
692 /**
693 * Reset the DoF handler pointer.
694 */
695 void
696 set_dof_handler(DoFHandler<dim, spacedim> *dh);
697
698 /**
699 * Set the index of the <i>i</i>th degree of freedom of this object to @p
700 * index.
701 *
702 * The last argument denotes the finite element index. For the standard
703 * ::DoFHandler class, this value must be equal to its default value since
704 * that class only supports the same finite element on all cells anyway.
705 *
706 * However, when the relevant DoFHandler has hp-capabilities, different
707 * finite element objects may be used on different cells. On faces between
708 * two cells, as well as vertices, there may therefore be two sets of
709 * degrees of freedom, one for each of the finite elements used on the
710 * adjacent cells. In order to specify which set of degrees of freedom to
711 * work on, the last argument is used to disambiguate. Finally, if this
712 * function is called for a cell object, there can only be a single set of
713 * degrees of freedom, and fe_index has to match the result of
714 * active_fe_index().
715 */
716 void
717 set_dof_index(
718 const unsigned int i,
719 const types::global_dof_index index,
720 const types::fe_index fe_index = numbers::invalid_fe_index) const;
721
722 void
723 set_mg_dof_index(const int level,
724 const unsigned int i,
725 const types::global_dof_index index) const;
726
727 void
728 set_mg_vertex_dof_index(
729 const int level,
730 const unsigned int vertex,
731 const unsigned int i,
732 const types::global_dof_index index,
733 const types::fe_index fe_index = numbers::invalid_fe_index) const;
734
735 // Iterator classes need to be friends because they need to access
736 // operator== and operator!=.
737 template <typename>
738 friend class TriaRawIterator;
739 template <int, int, int, bool>
740 friend class DoFAccessor;
741
742 private:
743 // Make the DoFHandler class a friend so that it can call the set_xxx()
744 // functions.
745 friend class DoFHandler<dim, spacedim>;
746
747 friend struct dealii::internal::DoFHandlerImplementation::Policy::
748 Implementation;
749 friend struct dealii::internal::DoFHandlerImplementation::Implementation;
750 friend struct dealii::internal::hp::DoFHandlerImplementation::Implementation;
751 friend struct dealii::internal::DoFCellAccessorImplementation::Implementation;
752 friend struct dealii::internal::DoFAccessorImplementation::Implementation;
753 };
754
755
756
757 /**
758 * Specialization of the general DoFAccessor class template for the case of
759 * zero-dimensional objects (a vertex) that are the face of a one-dimensional
760 * cell in spacedim space dimensions. Since vertices function differently than
761 * general faces, this class does a few things differently than the general
762 * template, but the interface should look the same.
763 */
764 template <int spacedim, bool level_dof_access>
765 class DoFAccessor<0, 1, spacedim, level_dof_access>
766 : public TriaAccessor<0, 1, spacedim>
767 {
768 public:
769 /**
770 * A static variable that allows users of this class to discover the value
771 * of the second template argument.
772 */
773 static constexpr unsigned int dimension = 1;
774
775 /**
776 * A static variable that allows users of this class to discover the value
777 * of the third template argument.
778 */
779 static constexpr unsigned int space_dimension = spacedim;
780
781 /**
782 * Declare an alias to the base class to make accessing some of the
783 * exception classes simpler.
784 */
785 using BaseClass = TriaAccessor<0, 1, spacedim>;
786
787 /**
788 * Data type passed by the iterator class.
789 */
790 using AccessorData = DoFHandler<1, spacedim>;
791
792 /**
793 * @name Constructors
794 */
795 /**
796 * @{
797 */
798
799 /**
800 * Default constructor. Provides an accessor that can't be used.
801 */
802 DoFAccessor();
803
804 /**
805 * Constructor to be used if the object here refers to a vertex of a
806 * one-dimensional triangulation, i.e. a face of the triangulation.
807 *
808 * Since there is no mapping from vertices to cells, an accessor object for
809 * a point has no way to figure out whether it is at the boundary of the
810 * domain or not. Consequently, the second argument must be passed by the
811 * object that generates this accessor -- e.g. a 1d cell that can figure out
812 * whether its left or right vertex are at the boundary.
813 *
814 * The third argument is the global index of the vertex we point to.
815 *
816 * The fourth argument is a pointer to the DoFHandler object.
817 *
818 * This iterator can only be called for one-dimensional triangulations.
819 */
820 DoFAccessor(
821 const Triangulation<1, spacedim> *tria,
822 const typename TriaAccessor<0, 1, spacedim>::VertexKind vertex_kind,
823 const unsigned int vertex_index,
824 const DoFHandler<1, spacedim> *dof_handler);
825
826 /**
827 * Constructor. This constructor exists in order to maintain interface
828 * compatibility with the other accessor classes. However, it doesn't do
829 * anything useful here and so may not actually be called except to
830 * default-construct iterator objects.
831 */
832 DoFAccessor(const Triangulation<1, spacedim> *,
833 const int = 0,
834 const int = 0,
835 const DoFHandler<1, spacedim> *dof_handler = 0);
836
837 /**
838 * Conversion constructor. This constructor exists to make certain
839 * constructs simpler to write in dimension independent code. For example,
840 * it allows assigning a face iterator to a line iterator, an operation that
841 * is useful in 2d but doesn't make any sense in 3d. The constructor here
842 * exists for the purpose of making the code conform to C++ but it will
843 * unconditionally abort; in other words, assigning a face iterator to a
844 * line iterator is better put into an if-statement that checks that the
845 * dimension is two, and assign to a quad iterator in 3d (an operator that,
846 * without this constructor would be illegal if we happen to compile for
847 * 2d).
848 */
849 template <int structdim2, int dim2, int spacedim2>
850 DoFAccessor(const InvalidAccessor<structdim2, dim2, spacedim2> &);
851
852 /**
853 * Another conversion operator between objects that don't make sense, just
854 * like the previous one.
855 */
856 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
857 DoFAccessor(
858 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &);
859
860 /**
861 * Copy constructor.
862 */
863 DoFAccessor(const DoFAccessor<0, 1, spacedim, level_dof_access> &) = default;
864
865 /**
866 * Move constructor.
867 */
868 // NOLINTNEXTLINE OSX does not compile with noexcept
869 DoFAccessor(DoFAccessor<0, 1, spacedim, level_dof_access> &&) = default;
870
871 /**
872 * Destructor.
873 */
874 ~DoFAccessor() = default;
875
876 /**
877 * Copy operator. These operators are usually used in a context like
878 * <tt>iterator a,b; *a=*b;</tt>. Presumably, the intent here is to copy the
879 * object pointed to
880 * by @p b to the object pointed to by @p a. However, the result of
881 * dereferencing an iterator is not an object but an accessor; consequently,
882 * this operation is not useful for iterators on DoF handler objects.
883 * Consequently, this operator is declared as deleted and can not be used.
884 */
885 DoFAccessor<0, 1, spacedim, level_dof_access> &
886 operator=(const DoFAccessor<0, 1, spacedim, level_dof_access> &da) = delete;
887
888 /**
889 * Move assignment operator.
890 */
891 DoFAccessor<0, 1, spacedim, level_dof_access> &
892 operator=(DoFAccessor<0, 1, spacedim, level_dof_access> &&) noexcept =
893 default;
894
895 /**
896 * @}
897 */
898
899 /**
900 * Return a handle on the DoFHandler object which we are using.
901 */
902 const DoFHandler<1, spacedim> &
903 get_dof_handler() const;
904
905 /**
906 * Implement the copy operator needed for the iterator classes.
907 */
908 template <bool level_dof_access2>
909 void
910 copy_from(const DoFAccessor<0, 1, spacedim, level_dof_access2> &a);
911
912 /**
913 * Copy operator used by the iterator class. Keeps the previously set dof
914 * handler, but sets the object coordinates of the TriaAccessor.
915 */
916 void
917 copy_from(const TriaAccessorBase<0, 1, spacedim> &da);
918
919 /**
920 * @name Accessing sub-objects
921 */
922 /**
923 * @{
924 */
925
926 /**
927 * Return an invalid iterator of a type that represents pointing to a child
928 * of the current object. The object is invalid because points (as
929 * represented by the current class) do not have children.
930 */
931 TriaIterator<DoFAccessor<0, 1, spacedim, level_dof_access>>
932 child(const unsigned int c) const;
933
934 /**
935 * Pointer to the @p ith line bounding this object.
936 *
937 * Since meshes with dimension 1 do not have quads this method just throws
938 * an exception.
939 */
940 typename dealii::internal::DoFHandlerImplementation::
941 Iterators<1, spacedim, level_dof_access>::line_iterator
942 line(const unsigned int i) const;
943
944 /**
945 * Pointer to the @p ith quad bounding this object.
946 *
947 * Since meshes with dimension 1 do not have quads this method just throws
948 * an exception.
949 */
950 typename dealii::internal::DoFHandlerImplementation::
951 Iterators<1, spacedim, level_dof_access>::quad_iterator
952 quad(const unsigned int i) const;
953
954 /**
955 * @}
956 */
957
958 /**
959 * @name Accessing the DoF indices of this object
960 */
961 /**
962 * @{
963 */
964
965 /**
966 * Return the <i>global</i> indices of the degrees of freedom located on
967 * this object in the standard ordering defined by the finite element. This
968 * function is only available on <i>active</i> objects (see
969 * @ref GlossActive "this glossary entry").
970 *
971 * The present vertex must belong to an active cell (and not artificial in a
972 * parallel distributed computation).
973 *
974 * The vector has to have the right size before being passed to this
975 * function.
976 *
977 * The last argument denotes the finite element index. For the standard
978 * ::DoFHandler class, this value must be equal to its default value since
979 * that class only supports the same finite element on all cells anyway.
980 *
981 * However, when the relevant DoFHandler has hp-capabilities, different
982 * finite element objects may be used on different cells. On faces between
983 * two cells, as well as vertices, there may therefore be two sets of
984 * degrees of freedom, one for each of the finite elements used on the
985 * adjacent cells. In order to specify which set of degrees of freedom to
986 * work on, the last argument is used to disambiguate. Finally, if this
987 * function is called for a cell object, there can only be a single set of
988 * degrees of freedom, and fe_index has to match the result of
989 * active_fe_index().
990 *
991 * For cells, there is only a single possible finite element index (namely
992 * the one for that cell, returned by <code>cell-@>active_fe_index</code>.
993 * Consequently, the derived DoFCellAccessor class has an overloaded version
994 * of this function that calls the present function with
995 * <code>cell-@>active_fe_index</code> as last argument.
996 */
997 void
998 get_dof_indices(
999 std::vector<types::global_dof_index> &dof_indices,
1000 const types::fe_index fe_index = numbers::invalid_fe_index) const;
1001
1002 /**
1003 * Return the global multilevel indices of the degrees of freedom that live
1004 * on the current object with respect to the given level within the
1005 * multigrid hierarchy. The indices refer to the local numbering for the
1006 * level this line lives on.
1007 */
1008 void
1009 get_mg_dof_indices(
1010 const int level,
1011 std::vector<types::global_dof_index> &dof_indices,
1012 const types::fe_index fe_index = numbers::invalid_fe_index) const;
1013
1014 /**
1015 * Global DoF index of the <i>i</i> degree associated with the @p vertexth
1016 * vertex of the present cell.
1017 *
1018 * The last argument denotes the finite element index. For the standard
1019 * ::DoFHandler class, this value must be equal to its default value since
1020 * that class only supports the same finite element on all cells anyway.
1021 *
1022 * However, when the relevant DoFHandler has hp-capabilities, different
1023 * finite element objects may be used on different cells. On faces between
1024 * two cells, as well as vertices, there may therefore be two sets of
1025 * degrees of freedom, one for each of the finite elements used on the
1026 * adjacent cells. In order to specify which set of degrees of freedom to
1027 * work on, the last argument is used to disambiguate. Finally, if this
1028 * function is called for a cell object, there can only be a single set of
1029 * degrees of freedom, and fe_index has to match the result of
1030 * active_fe_index().
1031 */
1032 types::global_dof_index
1033 vertex_dof_index(
1034 const unsigned int vertex,
1035 const unsigned int i,
1036 const types::fe_index fe_index = numbers::invalid_fe_index) const;
1037
1038 /**
1039 * Index of the <i>i</i>th degree of freedom of this object.
1040 *
1041 * The last argument denotes the finite element index. For the standard
1042 * ::DoFHandler class, this value must be equal to its default value since
1043 * that class only supports the same finite element on all cells anyway.
1044 *
1045 * However, when the relevant DoFHandler has hp-capabilities, different
1046 * finite element objects may be used on different cells. On faces between
1047 * two cells, as well as vertices, there may therefore be two sets of
1048 * degrees of freedom, one for each of the finite elements used on the
1049 * adjacent cells. In order to specify which set of degrees of freedom to
1050 * work on, the last argument is used to disambiguate. Finally, if this
1051 * function is called for a cell object, there can only be a single set of
1052 * degrees of freedom, and fe_index has to match the result of
1053 * active_fe_index().
1054 */
1055 types::global_dof_index
1056 dof_index(const unsigned int i,
1057 const types::fe_index fe_index = numbers::invalid_fe_index) const;
1058
1059 /**
1060 * @}
1061 */
1062
1063 /**
1064 * @name Accessing the finite element associated with this object
1065 */
1066 /**
1067 * @{
1068 */
1069
1070 /**
1071 * Return the number of finite elements that are active on a given object.
1072 *
1073 * Since vertices do not store the information necessary for this to be
1074 * calculated, this method just raises an exception and only exists to
1075 * enable dimension-independent programming.
1076 */
1077 unsigned int
1078 n_active_fe_indices() const;
1079
1080 /**
1081 * Return the @p n-th active FE index on this object.
1082 *
1083 * Since vertices do not store the information necessary for this to be
1084 * calculated, this method just raises an exception and only exists to
1085 * enable dimension-independent programming.
1086 */
1087 types::fe_index
1088 nth_active_fe_index(const unsigned int n) const;
1089
1090 /**
1091 * Return true if the finite element with given index is active on the
1092 * present object.
1093 *
1094 * Since vertices do not store the information necessary for this to be
1095 * calculated, this method just raises an exception and only exists to
1096 * enable dimension-independent programming.
1097 */
1098 bool
1099 fe_index_is_active(const types::fe_index fe_index) const;
1100
1101 /**
1102 * Return a reference to the finite element used on this object with the
1103 * given @p fe_index. @p fe_index must be used on this object, i.e.
1104 * <code>fe_index_is_active(fe_index)</code> must return true.
1105 */
1106 const FiniteElement<1, spacedim> &
1107 get_fe(const types::fe_index fe_index) const;
1108
1109 /**
1110 * @}
1111 */
1112
1113 /**
1114 * Exceptions for child classes
1115 *
1116 * @ingroup Exceptions
1117 */
1118 DeclExceptionMsg(ExcInvalidObject,
1119 "This accessor object has not been "
1120 "associated with any DoFHandler object.");
1121 /**
1122 * Exception
1123 *
1124 * @ingroup Exceptions
1125 */
1126 DeclException0(ExcVectorNotEmpty);
1127 /**
1128 * Exception
1129 *
1130 * @ingroup Exceptions
1131 */
1132 DeclException0(ExcVectorDoesNotMatch);
1133 /**
1134 * Exception
1135 *
1136 * @ingroup Exceptions
1137 */
1138 DeclException0(ExcMatrixDoesNotMatch);
1139 /**
1140 * A function has been called for a cell which should be
1141 * @ref GlossActive "active",
1142 * but is refined.
1143 *
1144 * @ingroup Exceptions
1145 */
1146 DeclException0(ExcNotActive);
1147 /**
1148 * Exception
1149 *
1150 * @ingroup Exceptions
1151 */
1152 DeclException0(ExcCantCompareIterators);
1153
1154 protected:
1155 /**
1156 * Store the address of the DoFHandler object to be accessed.
1157 */
1158 DoFHandler<1, spacedim> *dof_handler;
1159
1160 /**
1161 * Compare for equality.
1162 */
1163 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
1164 bool
1165 operator==(
1166 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
1167
1168 /**
1169 * Compare for inequality.
1170 */
1171 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
1172 bool
1173 operator!=(
1174 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
1175
1176 /**
1177 * Reset the DoF handler pointer.
1178 */
1179 void
1180 set_dof_handler(DoFHandler<1, spacedim> *dh);
1181
1182 /**
1183 * Set the index of the <i>i</i>th degree of freedom of this object to @p
1184 * index.
1185 *
1186 * The last argument denotes the finite element index. For the standard
1187 * ::DoFHandler class, this value must be equal to its default value since
1188 * that class only supports the same finite element on all cells anyway.
1189 *
1190 * However, when the relevant DoFHandler has hp-capabilities, different
1191 * finite element objects may be used on different cells. On faces between
1192 * two cells, as well as vertices, there may therefore be two sets of
1193 * degrees of freedom, one for each of the finite elements used on the
1194 * adjacent cells. In order to specify which set of degrees of freedom to
1195 * work on, the last argument is used to disambiguate. Finally, if this
1196 * function is called for a cell object, there can only be a single set of
1197 * degrees of freedom, and fe_index has to match the result of
1198 * active_fe_index().
1199 */
1200 void
1201 set_dof_index(
1202 const unsigned int i,
1203 const types::global_dof_index index,
1204 const types::fe_index fe_index = numbers::invalid_fe_index) const;
1205
1206 // Iterator classes need to be friends because they need to access
1207 // operator== and operator!=.
1208 template <typename>
1209 friend class TriaRawIterator;
1210
1211
1212 // Make the DoFHandler class a friend so that it can call the set_xxx()
1213 // functions.
1214 friend class DoFHandler<1, spacedim>;
1215
1216 friend struct dealii::internal::DoFHandlerImplementation::Policy::
1217 Implementation;
1218 friend struct dealii::internal::DoFHandlerImplementation::Implementation;
1219 friend struct dealii::internal::hp::DoFHandlerImplementation::Implementation;
1220 friend struct dealii::internal::DoFCellAccessorImplementation::Implementation;
1221 };
1222
1223
1224
1225 /* -------------------------------------------------------------------------- */
1226
1227
1228 /**
1229 * A class that represents DoF accessor objects to iterators that don't make
1230 * sense such as quad iterators in on 1d meshes. This class can not be used to
1231 * create objects (it will in fact throw an exception if this should ever be
1232 * attempted but it sometimes allows code to be written in a simpler way in a
1233 * dimension independent way. For example, it allows to write code that works
1234 * on quad iterators that is dimension independent -- i.e., also compiles
1235 * in 1d -- because quad iterators
1236 * (via the current class) exist and are syntactically correct. You can not
1237 * expect, however, to ever create an actual object of one of these iterators
1238 * in 1d, meaning you need to expect to wrap the code block in which you use
1239 * quad iterators into something like <code>if (dim@>1)</code> -- which makes
1240 * eminent sense anyway.
1241 *
1242 * This class provides the minimal interface necessary for Accessor classes to
1243 * interact with Iterator classes. However, this is only for syntactic
1244 * correctness, none of the functions do anything but generate errors.
1245 *
1246 * @ingroup Accessors
1247 */
1248 template <int structdim, int dim, int spacedim = dim>
1249 class DoFInvalidAccessor : public InvalidAccessor<structdim, dim, spacedim>
1250 {
1251 public:
1252 /**
1253 * Propagate alias from base class to this class.
1254 */
1255 using AccessorData =
1256 typename InvalidAccessor<structdim, dim, spacedim>::AccessorData;
1257
1258 /**
1259 * Constructor. This class is used for iterators that do not make
1260 * sense in a given dimension, for example quads for 1d meshes. Consequently,
1261 * while the creation of such objects is syntactically valid, they make no
1262 * semantic sense, and we generate an exception when such an object is
1263 * actually generated.
1264 */
1265 DoFInvalidAccessor(const void *parent = nullptr,
1266 const int level = -1,
1267 const int index = -1,
1268 const AccessorData *local_data = nullptr);
1269
1270 /**
1271 * Copy constructor. This class is used for iterators that do not make
1272 * sense in a given dimension, for example quads for 1d meshes. Consequently,
1273 * while the creation of such objects is syntactically valid, they make no
1274 * semantic sense, and we generate an exception when such an object is
1275 * actually generated.
1276 */
1277 DoFInvalidAccessor(const DoFInvalidAccessor<structdim, dim, spacedim> &);
1278
1279 /**
1280 * Conversion from other accessors to the current invalid one. This of
1281 * course also leads to a run-time error.
1282 */
1283 template <typename OtherAccessor>
1284 DoFInvalidAccessor(const OtherAccessor &);
1285
1286 /**
1287 * Return the index of the <i>i</i>th degree of freedom of this object to
1288 * @p index. Since the current object doesn't point to anything useful, like
1289 * all other functions in this class this function only throws an exception.
1290 */
1291 types::global_dof_index
1292 dof_index(const unsigned int i,
1293 const types::fe_index fe_index =
1294 DoFHandler<dim, spacedim>::default_fe_index) const;
1295
1296 /**
1297 * Set the index of the <i>i</i>th degree of freedom of this object to @p
1298 * index. Since the current object doesn't point to anything useful, like
1299 * all other functions in this class this function only throws an exception.
1300 */
1301 void
1302 set_dof_index(
1303 const unsigned int i,
1304 const types::global_dof_index index,
1305 const types::fe_index fe_index = numbers::invalid_fe_index) const;
1306 };
1307
1308
1309
1310 /* -------------------------------------------------------------------------- */
1311
1312
1313 /**
1314 * Grant access to the degrees of freedom on a cell.
1315 *
1316 * Note that since for the class we derive from, i.e.
1317 * <tt>DoFAccessor<dim></tt>, the two template parameters are equal, the base
1318 * class is actually derived from CellAccessor, which makes the functions of
1319 * this class available to the DoFCellAccessor class as well.
1320 *
1321 * @ingroup dofs
1322 * @ingroup Accessors
1323 */
1324 template <int dimension_, int space_dimension_, bool level_dof_access>
1325 class DoFCellAccessor : public DoFAccessor<dimension_,
1326 dimension_,
1327 space_dimension_,
1328 level_dof_access>
1329 {
1330 public:
1331 /**
1332 * Extract dimension from DoFHandler.
1333 */
1334 static const unsigned int dim = dimension_;
1335
1336 /**
1337 * Extract space dimension from DoFHandler.
1338 */
1339 static const unsigned int spacedim = space_dimension_;
1340
1341
1342 /**
1343 * Data type passed by the iterator class.
1344 */
1345 using AccessorData = DoFHandler<dimension_, space_dimension_>;
1346
1347 /**
1348 * Declare an alias to the base class to make accessing some of the
1349 * exception classes simpler.
1350 */
1351 using BaseClass =
1352 DoFAccessor<dimension_, dimension_, space_dimension_, level_dof_access>;
1353
1354 /**
1355 * Define the type of the container this is part of.
1356 */
1357 using Container = DoFHandler<dimension_, space_dimension_>;
1358
1359 /**
1360 * A type for an iterator over the faces of a cell. This is what the face()
1361 * function returns.
1362 */
1363 using face_iterator = TriaIterator<DoFAccessor<dimension_ - 1,
1364 dimension_,
1365 space_dimension_,
1366 level_dof_access>>;
1367
1368 /**
1369 * @name Constructors and initialization
1370 */
1371 /**
1372 * @{
1373 */
1374
1375 /**
1376 * Constructor
1377 */
1378 DoFCellAccessor(const Triangulation<dimension_, space_dimension_> *tria,
1379 const int level,
1380 const int index,
1381 const AccessorData *local_data);
1382
1383 /**
1384 * Conversion constructor. This constructor exists to make certain
1385 * constructs simpler to write in dimension independent code. For example,
1386 * it allows assigning a face iterator to a line iterator, an operation that
1387 * is useful in 2d but doesn't make any sense in 3d. The constructor here
1388 * exists for the purpose of making the code conform to C++ but it will
1389 * unconditionally abort; in other words, assigning a face iterator to a
1390 * line iterator is better put into an if-statement that checks that the
1391 * dimension is two, and assign to a quad iterator in 3d (an operator that,
1392 * without this constructor would be illegal if we happen to compile for
1393 * 2d).
1394 */
1395 template <int structdim2, int dim2, int spacedim2>
1396 DoFCellAccessor(const InvalidAccessor<structdim2, dim2, spacedim2> &);
1397
1398 /**
1399 * Another conversion operator between objects that don't make sense, just
1400 * like the previous one.
1401 */
1402 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
1403 explicit DoFCellAccessor(
1404 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &);
1405
1406 /**
1407 * Copy constructor.
1408 */
1409 DoFCellAccessor(
1410 const DoFCellAccessor<dimension_, space_dimension_, level_dof_access> &) =
1411 default;
1412
1413 /**
1414 * Move constructor.
1415 */
1416 DoFCellAccessor( // NOLINT
1417 DoFCellAccessor<dimension_, space_dimension_, level_dof_access> // NOLINT
1418 &&) = default; // NOLINT
1419
1420 /**
1421 * Destructor
1422 */
1423 ~DoFCellAccessor() = default;
1424
1425 /**
1426 * Copy operator. These operators are usually used in a context like
1427 * <tt>iterator a,b; *a=*b;</tt>. Presumably, the intent here is to copy the
1428 * object pointed to
1429 * by @p b to the object pointed to by @p a. However, the result of
1430 * dereferencing an iterator is not an object but an accessor; consequently,
1431 * this operation is not useful for iterators on DoF handler objects.
1432 * Consequently, this operator is declared as deleted and can not be used.
1433 */
1434 DoFCellAccessor<dimension_, space_dimension_, level_dof_access> &
1435 operator=(
1436 const DoFCellAccessor<dimension_, space_dimension_, level_dof_access> &da) =
1437 delete;
1438
1439 /**
1440 * Move assignment operator.
1441 */
1442 DoFCellAccessor<dimension_, space_dimension_, level_dof_access> & // NOLINT
1443 operator=( // NOLINT
1444 DoFCellAccessor<dimension_, space_dimension_, level_dof_access> // NOLINT
1445 &&) = default; // NOLINT
1446
1447 /**
1448 * @}
1449 */
1450
1451 /**
1452 * Return the parent of this cell as a DoF cell iterator. If the parent does
1453 * not exist (i.e., if the object is at the coarsest level of the mesh
1454 * hierarchy), an exception is generated.
1455 *
1456 * This function is needed since the parent function of the base class
1457 * CellAccessor returns a triangulation cell accessor without access to the
1458 * DoF data.
1459 */
1460 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
1461 parent() const;
1462
1463 /**
1464 * @name Accessing sub-objects and neighbors
1465 */
1466 /**
1467 * @{
1468 */
1469
1470 /**
1471 * Return the @p ith neighbor as a DoF cell iterator. This function is
1472 * needed since the neighbor function of the base class returns a cell
1473 * accessor without access to the DoF data.
1474 */
1475 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
1476 neighbor(const unsigned int i) const;
1477
1478 /**
1479 * Return the @p ith periodic neighbor as a DoF cell iterator. This function
1480 * is needed since the neighbor function of the base class returns a cell
1481 * accessor without access to the DoF data.
1482 */
1483 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
1484 periodic_neighbor(const unsigned int i) const;
1485
1486 /**
1487 * Return the @p ith neighbor or periodic neighbor as a DoF cell iterator.
1488 * This function is needed since the neighbor function of the base class
1489 * returns a cell accessor without access to the DoF data.
1490 */
1491 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
1492 neighbor_or_periodic_neighbor(const unsigned int i) const;
1493
1494 /**
1495 * Return the @p ith child as a DoF cell iterator. This function is needed
1496 * since the child function of the base class returns a cell accessor
1497 * without access to the DoF data.
1498 */
1499 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
1500 child(const unsigned int i) const;
1501
1502 /**
1503 * Return an array of iterators to all children of this cell.
1504 */
1505 boost::container::small_vector<
1506 TriaIterator<
1507 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>,
1508 GeometryInfo<dimension_>::max_children_per_cell>
1509 child_iterators() const;
1510
1511 /**
1512 * Return an iterator to the @p ith face of this cell.
1513 *
1514 * This function returns a DoFAccessor with <code>structdim == 0</code> in
1515 * 1d, a DoFAccessor::line in 2d, and a DoFAccessor::quad in 3d.
1516 */
1517 face_iterator
1518 face(const unsigned int i) const;
1519
1520 /**
1521 * Return an array of iterators to all faces of this cell.
1522 */
1523 boost::container::small_vector<face_iterator,
1524 GeometryInfo<dimension_>::faces_per_cell>
1525 face_iterators() const;
1526
1527 /**
1528 * Return the result of the @p neighbor_child_on_subface function of the
1529 * base class, but convert it so that one can also access the DoF data (the
1530 * function in the base class only returns an iterator with access to the
1531 * triangulation data).
1532 */
1533 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
1534 neighbor_child_on_subface(const unsigned int face_no,
1535 const unsigned int subface_no) const;
1536
1537 /**
1538 * Return the result of the @p periodic_neighbor_child_on_subface function
1539 * of the base class, but convert it so that one can also access the DoF
1540 * data (the function in the base class only returns an iterator with access
1541 * to the triangulation data).
1542 */
1543 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
1544 periodic_neighbor_child_on_subface(const unsigned int face_no,
1545 const unsigned int subface_no) const;
1546
1547 /**
1548 * @}
1549 */
1550
1551 /**
1552 * @name Extracting values from global vectors
1553 */
1554 /**
1555 * @{
1556 */
1557
1558 /**
1559 * Collect the values of the given vector restricted to the dofs of this cell
1560 * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
1561 * on line 0, dofs on line 1, etc, dofs on quad 0, etc. In other
1562 * words, this function implements a
1563 * [gather
1564 * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
1565 *
1566 * The vector has to have the right size before being passed to this
1567 * function. This function is only callable for active cells.
1568 *
1569 * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
1570 * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
1571 * compiled to support these libraries. It is in the responsibility of the
1572 * caller to assure that the types of the numbers stored in input and output
1573 * vectors are compatible and with similar accuracy.
1574 */
1575 template <class InputVector, typename number>
1576 void
1577 get_dof_values(const InputVector &values, Vector<number> &local_values) const;
1578
1579 /**
1580 * Collect the values of the given vector restricted to the dofs of this cell
1581 * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
1582 * on line 0, dofs on line 1, etc, dofs on quad 0, etc. In other
1583 * words, this function implements a
1584 * [gather
1585 * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
1586 *
1587 * The vector has to have the right size before being passed to this
1588 * function. This function is only callable for active cells.
1589 *
1590 * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
1591 * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
1592 * compiled to support these libraries. It is in the responsibility of the
1593 * caller to assure that the types of the numbers stored in input and output
1594 * vectors are compatible and with similar accuracy.
1595 */
1596 template <typename Number, typename ForwardIterator>
1597 void
1598 get_dof_values(const ReadVector<Number> &values,
1599 ForwardIterator local_values_begin,
1600 ForwardIterator local_values_end) const;
1601
1602 /**
1603 * Collect the values of the given vector restricted to the dofs of this cell
1604 * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
1605 * on line 0, dofs on line 1, etc, dofs on quad 0, etc. In other
1606 * words, this function implements a
1607 * [gather
1608 * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
1609 *
1610 * The vector has to have the right size before being passed to this
1611 * function. This function is only callable for active cells.
1612 *
1613 * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
1614 * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
1615 * compiled to support these libraries. It is in the responsibility of the
1616 * caller to assure that the types of the numbers stored in input and output
1617 * vectors are compatible and with similar accuracy. The
1618 * AffineConstraints object passed as an argument to this function makes
1619 * sure that constraints are correctly distributed when the dof values
1620 * are calculated.
1621 */
1622 template <class InputVector, typename ForwardIterator>
1623 void
1624 get_dof_values(
1625 const AffineConstraints<typename InputVector::value_type> &constraints,
1626 const InputVector &values,
1627 ForwardIterator local_values_begin,
1628 ForwardIterator local_values_end) const;
1629
1630 /**
1631 * This function is the counterpart to get_dof_values(): it takes a vector
1632 * of values for the degrees of freedom of the cell pointed to by this
1633 * iterator and writes these values into the global data vector @p values.
1634 * In other words, this function implements a
1635 * [scatter
1636 * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
1637 * This function is only callable for active cells.
1638 *
1639 * Note that for continuous finite elements, calling this function affects
1640 * the dof values on neighboring cells as well. It may also violate
1641 * continuity requirements for hanging nodes, if neighboring cells are less
1642 * refined than the present one. These requirements are not taken care of
1643 * and must be enforced by the user afterwards.
1644 *
1645 * The vector has to have the right size before being passed to this
1646 * function.
1647 *
1648 * The output vector may be either a Vector<float>, Vector<double>, or a
1649 * BlockVector<double>, or a PETSc vector if deal.II is compiled to support
1650 * these libraries. It is in the responsibility of the caller to assure that
1651 * the types of the numbers stored in input and output vectors are
1652 * compatible and with similar accuracy.
1653 */
1654 template <class OutputVector, typename number>
1655 void
1656 set_dof_values(const Vector<number> &local_values,
1657 OutputVector &values) const;
1658
1659 /**
1660 * Return the interpolation of the given finite element function to the
1661 * present cell. In the simplest case, the cell is a terminal one, i.e., it
1662 * has no children; then, the returned value is the vector of nodal values
1663 * on that cell. You could as well get the desired values through the @p
1664 * get_dof_values function. In the other case, when the cell has children,
1665 * we use the restriction matrices provided by the finite element class to
1666 * compute the interpolation from the children to the present cell.
1667 *
1668 * If the cell is part of a DoFHandler with hp-capabilities, cells only have
1669 * an associated finite element space if they are active. However, this
1670 * function is supposed to also provide information on inactive cells with
1671 * children. Consequently, it carries a third argument that can be used in
1672 * the hp-context that denotes the finite element space we are supposed to
1673 * interpolate onto. If the cell is active, this function then obtains the
1674 * finite element function from the <code>values</code> vector on this cell
1675 * and interpolates it onto the space described by the
1676 * <code>fe_index</code>th element of the hp::FECollection associated with
1677 * the DoFHandler of which this cell is a part of. If the cell is not
1678 * active, then we first perform this interpolation on all of its terminal
1679 * children and then interpolate this function down to the cell requested
1680 * keeping the function space the same.
1681 *
1682 * It is assumed that both input vectors already have the right size
1683 * beforehand.
1684 *
1685 * @note Unlike the get_dof_values() function, this function is only
1686 * available on cells, rather than on lines, quads, and hexes, since
1687 * interpolation is presently only provided for cells by the finite element
1688 * classes.
1689 */
1690 template <typename Number>
1691 void
1692 get_interpolated_dof_values(
1693 const ReadVector<Number> &values,
1694 Vector<Number> &interpolated_values,
1695 const types::fe_index fe_index = numbers::invalid_fe_index) const;
1696
1697 /**
1698 * This function is the counterpart to get_interpolated_dof_values(): you
1699 * specify the dof values on a cell and these are interpolated to the
1700 * children of the present cell and set on the terminal cells.
1701 *
1702 * In principle, it works as follows: if the cell pointed to by this object
1703 * is terminal (i.e., has no children), then the dof values are set in the
1704 * global data vector by calling the set_dof_values() function; otherwise,
1705 * the values are prolonged to each of the children and this function is
1706 * called for each of them.
1707 *
1708 * Using the get_interpolated_dof_values() and this function, you can
1709 * compute the interpolation of a finite element function to a coarser grid
1710 * by first getting the interpolated solution on a cell of the coarse grid
1711 * and afterwards redistributing it using this function.
1712 *
1713 * Note that for continuous finite elements, calling this function affects
1714 * the dof values on neighboring cells as well. It may also violate
1715 * continuity requirements for hanging nodes, if neighboring cells are less
1716 * refined than the present one, or if their children are less refined than
1717 * the children of this cell. These requirements are not taken care of and
1718 * must be enforced by the user afterward.
1719 *
1720 * If the cell is part of a DoFHandler with hp-capabilities, cells only have
1721 * an associated finite element space if they are active. However, this
1722 * function is supposed to also work on inactive cells with children.
1723 * Consequently, it carries a third argument that can be used in the
1724 * hp-context that denotes the finite element space we are supposed to
1725 * interpret the input vector of this function in. If the cell is active,
1726 * this function then interpolates the input vector interpreted as an
1727 * element of the space described by the <code>fe_index</code>th element of
1728 * the hp::FECollection associated with the DoFHandler of which this
1729 * cell is a part of, and interpolates it into the space that is associated
1730 * with this cell. On the other hand, if the cell is not active, then we
1731 * first perform this interpolation from this cell to its children using the
1732 * given <code>fe_index</code> until we end up on an active cell, at which
1733 * point we follow the procedure outlined at the beginning of the paragraph.
1734 *
1735 * It is assumed that both vectors already have the right size beforehand.
1736 * This function relies on the existence of a natural interpolation property
1737 * of finite element spaces of a cell to its children, denoted by the
1738 * prolongation matrices of finite element classes. For some elements, the
1739 * spaces on coarse and fine grids are not nested, in which case the
1740 * interpolation to a child is not the identity; refer to the documentation
1741 * of the respective finite element class for a description of what the
1742 * prolongation matrices represent in this case.
1743 *
1744 * @note Cells set the values of DoFs independently and might overwrite
1745 * previously set values in the global vector, for example when calling the
1746 * same function earlier from a different cell. By setting @p perform_check,
1747 * you can enable a check that the previous value and the one to be set here
1748 * are at least roughly the same. In practice, they might be slightly
1749 * different because they are computed in a way that theoretically ensures
1750 * that they are the same, but in practice they are only equal up to
1751 * round-off.
1752 *
1753 * @note Unlike the get_dof_values() function, this function is only
1754 * available on cells, rather than on lines, quads, and hexes, since
1755 * interpolation is presently only provided for cells by the finite element
1756 * classes.
1757 */
1758 template <class OutputVector, typename number>
1759 void
1760 set_dof_values_by_interpolation(
1761 const Vector<number> &local_values,
1762 OutputVector &values,
1763 const types::fe_index fe_index = numbers::invalid_fe_index,
1764 const bool perform_check = false) const;
1765
1766 /**
1767 * Similar to set_dof_values_by_interpolation() with the difference that
1768 * values are added into the vector.
1769 *
1770 * @note In parallel::distributed::SolutionTransfer, this function is used
1771 * to accumulate the contributions of all cells to a DoF; with a
1772 * subsequent multiplication with the inverse of the valence, finally,
1773 * the average value is obtained.
1774 */
1775 template <class OutputVector, typename number>
1776 void
1777 distribute_local_to_global_by_interpolation(
1778 const Vector<number> &local_values,
1779 OutputVector &values,
1780 const types::fe_index fe_index = numbers::invalid_fe_index) const;
1781
1782 /**
1783 * Distribute a local (cell based) vector to a global one by mapping the
1784 * local numbering of the degrees of freedom to the global one and entering
1785 * the local values into the global vector. In other words, this function
1786 * implements a
1787 * [scatter
1788 * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
1789 *
1790 * The elements are <em>added</em> to the existing elements in the global
1791 * vector, rather than just set, since this is usually what one wants. You may
1792 * also want to take a look at the
1793 * AffineConstraints::distribute_local_to_global() function if you need to
1794 * deal with constraints.
1795 */
1796 template <typename number, typename OutputVector>
1797 void
1798 distribute_local_to_global(const Vector<number> &local_source,
1799 OutputVector &global_destination) const;
1800
1801 /**
1802 * Distribute a local (cell based) vector in iterator format to a global one
1803 * by mapping the local numbering of the degrees of freedom to the global
1804 * one and entering the local values into the global vector.
1805 * In other words, this function implements a
1806 * [scatter
1807 * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
1808 *
1809 * The elements are <em>added</em> to the existing elements in the global
1810 * vector, rather than just set, since this is usually what one wants. You may
1811 * also want to take a look at the
1812 * AffineConstraints::distribute_local_to_global() function if you need to
1813 * deal with constraints.
1814 */
1815 template <typename ForwardIterator, typename OutputVector>
1816 void
1817 distribute_local_to_global(ForwardIterator local_source_begin,
1818 ForwardIterator local_source_end,
1819 OutputVector &global_destination) const;
1820
1821 /**
1822 * Distribute a local (cell based) vector in iterator format to a global one
1823 * by mapping the local numbering of the degrees of freedom to the global
1824 * one and entering the local values into the global vector.
1825 * In other words, this function implements a
1826 * [scatter
1827 * operation](https://en.wikipedia.org/wiki/Gather-scatter_(vector_addressing)).
1828 *
1829 * The elements are <em>added</em> up to the elements in the global vector,
1830 * rather than just set, since this is usually what one wants. Moreover, the
1831 * AffineConstraints object passed to this function makes sure that also
1832 * constraints are eliminated in this process.
1833 */
1834 template <typename ForwardIterator, typename OutputVector>
1835 void
1836 distribute_local_to_global(
1837 const AffineConstraints<typename OutputVector::value_type> &constraints,
1838 ForwardIterator local_source_begin,
1839 ForwardIterator local_source_end,
1840 OutputVector &global_destination) const;
1841
1842 /**
1843 * This function does much the same as the
1844 * <tt>distribute_local_to_global(Vector,Vector)</tt> function, but operates
1845 * on matrices instead of vectors. If the matrix type is a sparse matrix
1846 * then it is supposed to have non-zero entry slots where required.
1847 */
1848 template <typename number, typename OutputMatrix>
1849 void
1850 distribute_local_to_global(const FullMatrix<number> &local_source,
1851 OutputMatrix &global_destination) const;
1852
1853 /**
1854 * This function does what the two <tt>distribute_local_to_global</tt>
1855 * functions with vector and matrix argument do, but all at once.
1856 */
1857 template <typename number, typename OutputMatrix, typename OutputVector>
1858 void
1859 distribute_local_to_global(const FullMatrix<number> &local_matrix,
1860 const Vector<number> &local_vector,
1861 OutputMatrix &global_matrix,
1862 OutputVector &global_vector) const;
1863
1864 /**
1865 * @}
1866 */
1867
1868 /**
1869 * @name Accessing the DoF indices of this object
1870 */
1871
1872 /**
1873 * @{
1874 */
1875
1876 /**
1877 * Obtain the global indices of the local degrees of freedom on this cell.
1878 *
1879 * If this object accesses a level cell (indicated by the third template
1880 * argument or #is_level_cell), then return the result of
1881 * get_mg_dof_indices(), else return get_dof_indices().
1882 *
1883 * You will get a level_cell_iterator when calling begin_mg() and a normal
1884 * one otherwise.
1885 *
1886 * Examples for this use are in the implementation of DoFRenumbering.
1887 */
1888 void
1889 get_active_or_mg_dof_indices(
1890 std::vector<types::global_dof_index> &dof_indices) const;
1891
1892 /**
1893 * Return the <i>global</i> indices of the degrees of freedom located on
1894 * this object in the standard ordering defined by the finite element (i.e.,
1895 * dofs on vertex 0, dofs on vertex 1, etc, dofs on line 0, dofs on line 1,
1896 * etc, dofs on quad 0, etc.) This function is only available on
1897 * <i>active</i> objects (see
1898 * @ref GlossActive "this glossary entry").
1899 *
1900 * @param[out] dof_indices The vector into which the indices will be
1901 * written. It has to have the right size (namely,
1902 * <code>fe.n_dofs_per_cell()</code>, <code>fe.dofs_per_face</code>, or
1903 * <code>fe.dofs_per_line</code>, depending on which kind of object this
1904 * function is called) before being passed to this function.
1905 *
1906 * This function reimplements the same function in the base class. In
1907 * contrast to the function in the base class, we do not need the
1908 * <code>fe_index</code> here because there is always a unique finite
1909 * element index on cells.
1910 *
1911 * This is a function which requires that the cell is active.
1912 *
1913 * Also see get_active_or_mg_dof_indices().
1914 *
1915 * @note In many places in the tutorial and elsewhere in the library, the
1916 * argument to this function is called <code>local_dof_indices</code> by
1917 * convention. The name is not meant to indicate the <i>local</i> numbers of
1918 * degrees of freedom (which are always between zero and
1919 * <code>fe.n_dofs_per_cell()</code>) but instead that the returned values are
1920 * the <i>global</i> indices of those degrees of freedom that are located
1921 * locally on the current cell.
1922 */
1923 void
1924 get_dof_indices(std::vector<types::global_dof_index> &dof_indices) const;
1925
1926 /**
1927 * Retrieve the global indices of the degrees of freedom on this cell in the
1928 * level vector associated to the level of the cell.
1929 */
1930 void
1931 get_mg_dof_indices(std::vector<types::global_dof_index> &dof_indices) const;
1932
1933 /**
1934 * @}
1935 */
1936
1937 /**
1938 * @name Accessing the finite element associated with this object
1939 */
1940 /**
1941 * @{
1942 */
1943
1944 /**
1945 * Return the finite element that is used on the cell pointed to by this
1946 * iterator. For DoFHandler objects without hp-capabilities, this is of
1947 * course always the same element, independent of the cell we are presently
1948 * on, but for hp-DoFHandler objects this may change from cell to cell.
1949 *
1950 * @note Since degrees of freedom only exist on active cells for DoFHandler
1951 * objects with hp-capabilities (i.e., there is currently no implementation
1952 * of multilevel such objects), it does not make sense to query the finite
1953 * element on non-active cells since they do not have finite element spaces
1954 * associated with them without having any degrees of freedom. Consequently,
1955 * this function will produce an exception when called on non-active cells.
1956 */
1957 const FiniteElement<dimension_, space_dimension_> &
1958 get_fe() const;
1959
1960 /**
1961 * Return the index inside the hp::FECollection of the FiniteElement used
1962 * for this cell. This function is only useful if the DoFHandler object
1963 * associated with the current cell has hp-capabilities enabled.
1964 *
1965 * @note Since degrees of freedom only exist on active cells for DoFHandler
1966 * objects with hp-capabilities (i.e., there is currently no implementation
1967 * of multilevel such objects), it does not make sense to query the finite
1968 * element on non-active cells since they do not have finite element spaces
1969 * associated with them without having any degrees of freedom. Consequently,
1970 * this function will produce an exception when called on non-active cells.
1971 *
1972 * @note When using parallel meshes, either through the
1973 * parallel::shared::Triangulation or parallel::distributed::Triangulation
1974 * classes, it is only allowed to call this function on locally
1975 * owned or ghost cells. No information is available on artificial cells.
1976 * Furthermore, @p active_fe_index information is only exchanged from locally
1977 * owned cells on one processor to other processors where they may be
1978 * ghost cells, during the call to DoFHandler::set_fe() and
1979 * DoFHandler::distribute_dofs(). Be aware that if you call
1980 * set_active_fe_index() on a cell after calling one of these functions, then
1981 * this information will not be propagated to other processors who may have
1982 * this cell as a ghost cell. See the documentation of DoFHandler for more
1983 * information.
1984 */
1985 types::fe_index
1986 active_fe_index() const;
1987
1988 /**
1989 * Set the index of the FiniteElement used for this cell. This determines
1990 * which element in an hp::FECollection to use. This function is only useful
1991 * if the DoF handler object associated with the current cell has
1992 * hp-capabilities enabled.
1993 *
1994 * @note Since degrees of freedom only exist on active cells for DoFHandler
1995 * objects with hp-capabilities (i.e., there is currently no implementation
1996 * of multilevel such objects), it does not make sense to query the finite
1997 * element on non-active cells since they do not have finite element spaces
1998 * associated with them without having any degrees of freedom. Consequently,
1999 * this function will produce an exception when called on non-active cells.
2000 *
2001 * @note When using parallel meshes, either through the
2002 * parallel::shared::Triangulation or parallel::distributed::Triangulation
2003 * classes, it is only allowed to call this function on locally
2004 * owned or ghost cells. No information is available on artificial cells.
2005 * Furthermore, @p active_fe_index information is only exchanged from locally
2006 * owned cells on one processor to other processors where they may be
2007 * ghost cells, during the call to DoFHandler::set_fe() and
2008 * DoFHandler::distribute_dofs(). Be aware that if you call
2009 * set_active_fe_index() on a cell after calling one of these functions, then
2010 * this information will not be propagated to other processors who may have
2011 * this cell as a ghost cell. See the documentation of DoFHandler for more
2012 * information.
2013 */
2014 void
2015 set_active_fe_index(const types::fe_index i) const;
2016 /**
2017 * @}
2018 */
2019
2020 /**
2021 * Set the DoF indices of this cell to the given values. This function
2022 * bypasses the DoF cache, if one exists for the given DoF handler class.
2023 */
2024 void
2025 set_dof_indices(const std::vector<types::global_dof_index> &dof_indices);
2026
2027 /**
2028 * Set the Level DoF indices of this cell to the given values.
2029 */
2030 void
2031 set_mg_dof_indices(const std::vector<types::global_dof_index> &dof_indices);
2032
2033 /**
2034 * @name Dealing with refinement indicators
2035 */
2036 /**
2037 * @{
2038 */
2039
2040 /**
2041 * Return the finite element that will be assigned to this cell next time the
2042 * triangulation gets refined and coarsened. If no future finite element has
2043 * been specified for this cell via the set_future_fe_index() function, the
2044 * active one will remain unchanged, in which case the active finite element
2045 * will be returned.
2046 *
2047 * For DoFHandlers without hp-capabilities enabled, this is of course always
2048 * the same element, independent of the cell we are presently on, but for
2049 * hp-DoFHandler objects this may change from cell to cell.
2050 *
2051 * @note Since degrees of freedom only exist on active cells for DoFHandler
2052 * objects with hp-capabilities (i.e., there is currently no implementation
2053 * of multilevel such objects), it does not make sense to query the finite
2054 * element on non-active cells since they do not have finite element spaces
2055 * associated with them without having any degrees of freedom. Consequently,
2056 * this function will produce an exception when called on non-active cells.
2057 */
2058 const FiniteElement<dimension_, space_dimension_> &
2059 get_future_fe() const;
2060
2061 /**
2062 * Return the fe_index of the finite element that will be assigned to this
2063 * cell next time the triangulation gets refined and coarsened. If no future
2064 * finite element has been specified for this cell via the
2065 * set_future_fe_index() function, the active one will remain unchanged, in
2066 * which case the fe_index of the active finite element will be returned.
2067 *
2068 * @note Since degrees of freedom only exist on active cells for DoFHandler
2069 * objects with hp-capabilities (i.e., there is currently no implementation
2070 * of multilevel such objects), it does not make sense to query the finite
2071 * element on non-active cells since they do not have finite element spaces
2072 * associated with them without having any degrees of freedom. Consequently,
2073 * this function will produce an exception when called on non-active cells.
2074 *
2075 * @note When using parallel meshes, either through the
2076 * parallel::shared::Triangulation or parallel::distributed::Triangulation
2077 * classes, it is only allowed to call this function on locally owned cells.
2078 */
2079 types::fe_index
2080 future_fe_index() const;
2081
2082 /**
2083 * Set the fe_index of the finite element that will be assigned to this
2084 * cell next time the triangulation gets refined and coarsened. A previously
2085 * assigned future finite element will be overwritten.
2086 *
2087 * See notes of future_fe_index() for information about restrictions on this
2088 * functionality.
2089 */
2090 void
2091 set_future_fe_index(const types::fe_index i) const;
2092
2093 /**
2094 * Return whether a future finite element has been set.
2095 *
2096 * See notes of future_fe_index() for information about restrictions on this
2097 * functionality.
2098 */
2099 bool
2100 future_fe_index_set() const;
2101
2102 /**
2103 * Revoke the future finite element assigned. Thus, the active finite element
2104 * will remain unchanged next time the triangulation gets refined and
2105 * coarsened.
2106 *
2107 * See notes on future_fe_index() for information about restrictions on this
2108 * functionality.
2109 */
2110 void
2111 clear_future_fe_index() const;
2112 /**
2113 * @}
2114 */
2115
2116 private:
2117 friend struct dealii::internal::DoFCellAccessorImplementation::Implementation;
2118 };
2119
2120
2121 template <int structdim, int dim, int spacedim, bool level_dof_access>
2122 inline bool
2123 DoFAccessor<structdim, dim, spacedim, level_dof_access>::is_level_cell()
2124 {
2125 return level_dof_access;
2126 }
2127
2128
2129
2130 template <int structdim, int dim, int spacedim>
2131 template <typename OtherAccessor>
2132 DoFInvalidAccessor<structdim, dim, spacedim>::DoFInvalidAccessor(
2133 const OtherAccessor &)
2134 {
2135 Assert(false,
2136 ExcMessage("You are attempting an illegal conversion between "
2137 "iterator/accessor types. The constructor you call "
2138 "only exists to make certain template constructs "
2139 "easier to write as dimension independent code but "
2140 "the conversion is not valid in the current context."));
2141 }
2142
2143
2144
2145 /*------------------------- Functions: DoFAccessor ---------------------------*/
2146
2147
2148 template <int structdim, int dim, int spacedim, bool level_dof_access>
2149 inline DoFAccessor<structdim, dim, spacedim, level_dof_access>::DoFAccessor()
2150 {
2151 Assert(false, ExcInvalidObject());
2152 }
2153
2154
2155
2156 template <int structdim, int dim, int spacedim, bool level_dof_access>
2157 inline DoFAccessor<structdim, dim, spacedim, level_dof_access>::DoFAccessor(
2158 const Triangulation<dim, spacedim> *tria,
2159 const int level,
2160 const int index,
2161 const DoFHandler<dim, spacedim> *dof_handler)
2162 : dealii::internal::DoFAccessorImplementation::
2163 Inheritance<structdim, dim, spacedim>::BaseClass(tria, level, index)
2164 , dof_handler(const_cast<DoFHandler<dim, spacedim> *>(dof_handler))
2165 {
2166 Assert(
2167 tria == nullptr || &dof_handler->get_triangulation() == tria,
2168 ExcMessage(
2169 "You can't create a DoF accessor in which the DoFHandler object "
2170 "uses a different triangulation than the one you pass as argument."));
2171 }
2172
2173
2174
2175 template <int structdim, int dim, int spacedim, bool level_dof_access>
2176 template <int structdim2, int dim2, int spacedim2>
2177 DoFAccessor<structdim, dim, spacedim, level_dof_access>::DoFAccessor(
2178 const InvalidAccessor<structdim2, dim2, spacedim2> &)
2179 {
2180 Assert(false, ExcInvalidObject());
2181 }
2182
2183
2184
2185 template <int structdim, int dim, int spacedim, bool level_dof_access>
2186 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
2187 inline DoFAccessor<structdim, dim, spacedim, level_dof_access>::DoFAccessor(
2188 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &other)
2189 : BaseClass(other)
2190 , dof_handler(nullptr)
2191 {
2192 Assert(false,
2193 ExcMessage(
2194 "You are trying to assign iterators that are incompatible. "
2195 "The reason for incompatibility is that they refer to objects of "
2196 "different dimensionality (e.g., assigning a line iterator "
2197 "to a quad iterator)."));
2198 }
2199
2200
2201
2202 template <int structdim, int dim, int spacedim, bool level_dof_access>
2203 template <bool level_dof_access2>
2204 inline DoFAccessor<structdim, dim, spacedim, level_dof_access>::DoFAccessor(
2205 const DoFAccessor<structdim, dim, spacedim, level_dof_access2> &other)
2206 : BaseClass(other)
2207 , dof_handler(const_cast<DoFHandler<dim, spacedim> *>(other.dof_handler))
2208 {}
2209
2210
2211
2212 template <int structdim, int dim, int spacedim, bool level_dof_access>
2213 inline void
2214 DoFAccessor<structdim, dim, spacedim, level_dof_access>::set_dof_handler(
2215 DoFHandler<dim, spacedim> *dh)
2216 {
2217 Assert(dh != nullptr, ExcInvalidObject());
2218 this->dof_handler = dh;
2219 }
2220
2221
2222
2223 template <int structdim, int dim, int spacedim, bool level_dof_access>
2224 inline const DoFHandler<dim, spacedim> &
2225 DoFAccessor<structdim, dim, spacedim, level_dof_access>::get_dof_handler() const
2226 {
2227 Assert(this->dof_handler != nullptr, ExcInvalidObject());
2228 return *this->dof_handler;
2229 }
2230
2231
2232
2233 template <int structdim, int dim, int spacedim, bool level_dof_access>
2234 inline void
2235 DoFAccessor<structdim, dim, spacedim, level_dof_access>::copy_from(
2236 const TriaAccessorBase<structdim, dim, spacedim> &da)
2237 {
2238 Assert(this->dof_handler != nullptr, ExcInvalidObject());
2239 BaseClass::copy_from(da);
2240 }
2241
2242
2243
2244 template <int structdim, int dim, int spacedim, bool level_dof_access>
2245 template <bool level_dof_access2>
2246 inline void
2247 DoFAccessor<structdim, dim, spacedim, level_dof_access>::copy_from(
2248 const DoFAccessor<structdim, dim, spacedim, level_dof_access2> &a)
2249 {
2250 BaseClass::copy_from(a);
2251 this->dof_handler = a.dof_handler;
2252 }
2253
2254
2255
2256 template <int structdim, int dim, int spacedim, bool level_dof_access>
2257 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
2258 inline bool
2259 DoFAccessor<structdim, dim, spacedim, level_dof_access>::operator==(
2260 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &a) const
2261 {
2262 Assert(structdim == structdim2, ExcCantCompareIterators());
2263 Assert(this->dof_handler == a.dof_handler, ExcCantCompareIterators());
2264 return (BaseClass::operator==(a));
2265 }
2266
2267
2268
2269 template <int structdim, int dim, int spacedim, bool level_dof_access>
2270 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
2271 inline bool
2272 DoFAccessor<structdim, dim, spacedim, level_dof_access>::operator!=(
2273 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &a) const
2274 {
2275 Assert(structdim == structdim2, ExcCantCompareIterators());
2276 Assert(this->dof_handler == a.dof_handler, ExcCantCompareIterators());
2277 return (BaseClass::operator!=(a));
2278 }
2279
2280
2281
2282 template <int structdim, int dim, int spacedim, bool level_dof_access>
2283 inline TriaIterator<DoFAccessor<structdim, dim, spacedim, level_dof_access>>
2284 DoFAccessor<structdim, dim, spacedim, level_dof_access>::child(
2285 const unsigned int i) const
2286 {
2287 Assert(static_cast<unsigned int>(this->present_level) <
2288 this->dof_handler->object_dof_indices.size(),
2289 ExcMessage("DoFHandler not initialized"));
2290
2291 TriaIterator<TriaAccessor<structdim, dim, spacedim>> t =
2292 TriaAccessor<structdim, dim, spacedim>::child(i);
2293
2294 TriaIterator<DoFAccessor<structdim, dim, spacedim, level_dof_access>> q(
2295 *t, this->dof_handler);
2296 return q;
2297 }
2298
2299
2300 namespace internal
2301 {
2302 namespace DoFAccessorImplementation
2303 {
2304 /**
2305 * Convert an FE index that might contain the right value but also
2306 * numbers::invalid_fe_index to a right value if needed/possible.
2307 */
2308 template <int structdim, int dim, int spacedim, bool level_dof_access>
2309 types::fe_index
2310 get_fe_index_or_default(
2311 const DoFAccessor<structdim, dim, spacedim, level_dof_access> &cell,
2312 const types::fe_index fe_index)
2313 {
2314 if (cell.get_dof_handler().has_hp_capabilities() == false)
2315 {
2316 // No hp enabled, and the argument is at its default value -> we
2317 // can translate to the default active fe index
2318 Assert(
2319 (fe_index == numbers::invalid_fe_index) ||
2320 (fe_index == DoFHandler<dim, spacedim>::default_fe_index),
2321 ExcMessage(
2322 "It is not possible to specify a FE index if no hp support is used!"));
2323
2324 return DoFHandler<dim, spacedim>::default_fe_index;
2325 }
2326 else
2327 {
2328 // Otherwise: If anything other than the default is provided by
2329 // the caller, then we should take just that. As an exception, if
2330 // we are on a cell (rather than a face/edge/vertex), then we know
2331 // that there is only one active fe index on this cell and we can
2332 // use that:
2333 if ((dim == structdim) && (fe_index == numbers::invalid_fe_index))
2334 {
2335 AssertDimension(cell.n_active_fe_indices(), 1);
2336
2337 return cell.nth_active_fe_index(0);
2338 }
2339
2340 Assert((fe_index != numbers::invalid_fe_index),
2341 ExcMessage(
2342 "You need to specify a FE index if hp support is used!"));
2343
2344 return fe_index;
2345 }
2346 }
2347
2348 /**
2349 * A class like the one with same name in tria.cc. See there for more
2350 * information.
2351 */
2352 struct Implementation
2353 {
2354 /**
2355 * In several applications of DoFAccessor::get_dof_values(), we want to
2356 * extract some indices without having to allocate memory. We do this by
2357 * setting a boost small_vector with 27 elements on the stack, and only
2358 * allocate when we exceed 27. The number 27 is heuristic and allows up
2359 * to quadratic shape functions on scalar problems in 3d, or linear
2360 * shape functions on systems (elasticity).
2361 */
2362 using dof_index_vector_type =
2363 boost::container::small_vector<dealii::types::global_dof_index, 27>;
2364
2365 /**
2366 * Process the @p local_index-th degree of freedom corresponding to the
2367 * finite element specified by @p fe_index on the vertex with global
2368 * number @p vertex_index to @p global_index.
2369 *
2370 * The template argument `structdim` indicates the
2371 * dimensionality of the object on which we seek to know the DoF
2372 * index. For example, if `structdim==0`, then we are looking to
2373 * get a DoF index on a vertex of the indicated cell.
2374 */
2375 template <int dim,
2376 int spacedim,
2377 int structdim,
2378 typename GlobalIndexType,
2379 typename DoFPProcessor>
2380 static void
2381 process_dof_index(const DoFHandler<dim, spacedim> &dof_handler,
2382 const unsigned int obj_level,
2383 const unsigned int obj_index,
2384 const types::fe_index fe_index,
2385 const unsigned int local_index,
2386 const std::integral_constant<int, structdim> &,
2387 GlobalIndexType &global_index,
2388 const DoFPProcessor &process)
2389 {
2390 Assert(structdim == dim || obj_level == 0, ExcNotImplemented());
2391
2392 // 1) no hp used -> fe_index == 0
2393 if (dof_handler.hp_capability_enabled == false)
2394 {
2395 AssertDimension(fe_index,
2396 (DoFHandler<dim, spacedim>::default_fe_index));
2397
2398 process(
2399 dof_handler.object_dof_indices
2400 [obj_level][structdim]
2401 [dof_handler.object_dof_ptr[obj_level][structdim][obj_index] +
2402 local_index],
2403 global_index);
2404
2405 return;
2406 }
2407
2408 // 2) cell and hp is used -> there is only one fe_index
2409 if (structdim == dim)
2410 {
2411 process(
2412 dof_handler.object_dof_indices
2413 [obj_level][structdim]
2414 [dof_handler.object_dof_ptr[obj_level][structdim][obj_index] +
2415 local_index],
2416 global_index);
2417 return;
2418 }
2419
2420 // 3) general entity and hp is used
2421 AssertIndexRange(obj_level, dof_handler.object_dof_indices.size());
2422 AssertIndexRange(structdim,
2423 dof_handler.object_dof_indices[obj_level].size());
2424
2425 Assert(dof_handler.hp_capability_enabled, ExcInternalError());
2426
2427 AssertIndexRange(structdim, dof_handler.hp_object_fe_ptr.size());
2428 AssertIndexRange(obj_index,
2429 dof_handler.hp_object_fe_ptr[structdim].size());
2430
2431 const auto ptr =
2432 std::find(dof_handler.hp_object_fe_indices[structdim].begin() +
2433 dof_handler.hp_object_fe_ptr[structdim][obj_index],
2434 dof_handler.hp_object_fe_indices[structdim].begin() +
2435 dof_handler.hp_object_fe_ptr[structdim][obj_index + 1],
2436 fe_index);
2437
2438 Assert(ptr != dof_handler.hp_object_fe_indices[structdim].begin() +
2439 dof_handler.hp_object_fe_ptr[structdim][obj_index + 1],
2440 ExcMessage(
2441 "You are requesting an active FE index that is not assigned "
2442 "to any of the cells connected to this entity."));
2443
2444 const types::fe_index fe_index_ =
2445 std::distance(dof_handler.hp_object_fe_indices[structdim].begin() +
2446 dof_handler.hp_object_fe_ptr[structdim][obj_index],
2447 ptr);
2448
2449 AssertIndexRange(
2450 dof_handler.hp_capability_enabled ?
2451 (dof_handler.hp_object_fe_ptr[structdim][obj_index] + fe_index_) :
2452 obj_index,
2453 dof_handler.object_dof_ptr[obj_level][structdim].size());
2454
2455 AssertIndexRange(
2456 dof_handler.object_dof_ptr
2457 [obj_level][structdim]
2458 [dof_handler.hp_capability_enabled ?
2459 (dof_handler.hp_object_fe_ptr[structdim][obj_index] +
2460 fe_index_) :
2461 obj_index] +
2462 local_index,
2463 dof_handler.object_dof_indices[obj_level][structdim].size());
2464
2465 process(dof_handler.object_dof_indices
2466 [obj_level][structdim]
2467 [dof_handler.object_dof_ptr
2468 [obj_level][structdim]
2469 [dof_handler.hp_capability_enabled ?
2470 (dof_handler.hp_object_fe_ptr[structdim][obj_index] +
2471 fe_index_) :
2472 obj_index] +
2473 local_index],
2474 global_index);
2475 }
2476
2477 /**
2478 * Determine start index and number of dofs of object in global data
2479 * structure.
2480 *
2481 * The template argument `structdim` indicates the
2482 * dimensionality of the object on which we seek to know the DoF
2483 * index. For example, if `structdim==0`, then we are looking to
2484 * get a DoF index on a vertex of the indicated cell.
2485 */
2486 template <int dim, int spacedim, int structdim>
2487 static std::pair<unsigned int, unsigned int>
2488 process_object_range(const DoFHandler<dim, spacedim> &dof_handler,
2489 const unsigned int obj_level,
2490 const unsigned int obj_index,
2491 const types::fe_index fe_index,
2492 const std::integral_constant<int, structdim> &)
2493 {
2494 Assert(structdim == dim || obj_level == 0, ExcNotImplemented());
2495
2496 // determine range of dofs in global data structure
2497 // 1) cell
2498 if (structdim == dim)
2499 {
2500 const unsigned int ptr_0 =
2501 dof_handler.object_dof_ptr[obj_level][structdim][obj_index];
2502 const unsigned int length =
2503 dof_handler.get_fe(fe_index).template n_dofs_per_object<dim>(0);
2504
2505 return {ptr_0, length};
2506 }
2507
2508 // 2) hp is not used -> fe_index == 0
2509 if (dof_handler.hp_capability_enabled == false)
2510 {
2511 AssertDimension(fe_index,
2512 (DoFHandler<dim, spacedim>::default_fe_index));
2513
2514 const unsigned int ptr_0 =
2515 dof_handler.object_dof_ptr[obj_level][structdim][obj_index];
2516 const unsigned int length =
2517 dof_handler.object_dof_ptr[obj_level][structdim][obj_index + 1] -
2518 ptr_0;
2519
2520 return {ptr_0, length};
2521 }
2522
2523 // 3) hp is used
2524 AssertIndexRange(obj_level, dof_handler.object_dof_indices.size());
2525 AssertIndexRange(structdim,
2526 dof_handler.object_dof_indices[obj_level].size());
2527
2528 AssertIndexRange(structdim, dof_handler.hp_object_fe_ptr.size());
2529 AssertIndexRange(obj_index,
2530 dof_handler.hp_object_fe_ptr[structdim].size());
2531
2532 const auto fe_index_local_ptr =
2533 std::find(dof_handler.hp_object_fe_indices[structdim].begin() +
2534 dof_handler.hp_object_fe_ptr[structdim][obj_index],
2535 dof_handler.hp_object_fe_indices[structdim].begin() +
2536 dof_handler.hp_object_fe_ptr[structdim][obj_index + 1],
2537 fe_index);
2538
2539 Assert(fe_index_local_ptr !=
2540 dof_handler.hp_object_fe_indices[structdim].begin() +
2541 dof_handler.hp_object_fe_ptr[structdim][obj_index + 1],
2542 ExcMessage(
2543 "You tried to call a function accessing DoF indices, but "
2544 "they appear not be available (yet) or inconsistent. "
2545 "Did you call distribute_dofs() first? Alternatively, if "
2546 "you are using different elements on different cells (i.e., "
2547 "you are using the hp capabilities of deal.II), did you "
2548 "change the active_fe_index of a cell since you last "
2549 "called distribute_dofs()?"));
2550
2551 const types::fe_index fe_index_local =
2552 std::distance(dof_handler.hp_object_fe_indices[structdim].begin() +
2553 dof_handler.hp_object_fe_ptr[structdim][obj_index],
2554 fe_index_local_ptr);
2555
2556 AssertIndexRange(
2557 dof_handler.hp_object_fe_ptr[structdim][obj_index] + fe_index_local,
2558 dof_handler.object_dof_ptr[obj_level][structdim].size());
2559
2560 const unsigned int ptr_0 =
2561 dof_handler
2562 .object_dof_ptr[obj_level][structdim]
2563 [dof_handler.hp_object_fe_ptr[structdim][obj_index] +
2564 fe_index_local];
2565 const unsigned int ptr_1 =
2566 dof_handler
2567 .object_dof_ptr[obj_level][structdim]
2568 [dof_handler.hp_object_fe_ptr[structdim][obj_index] +
2569 fe_index_local + 1];
2570
2571 return {ptr_0, ptr_1 - ptr_0};
2572 }
2573
2574 template <int dim, int spacedim, int structdim, bool level_dof_access>
2575 static std::pair<unsigned int, unsigned int>
2576 process_object_range(
2577 const dealii::DoFAccessor<structdim, dim, spacedim, level_dof_access>
2578 accessor,
2579 const types::fe_index fe_index)
2580 {
2581 return process_object_range(accessor.get_dof_handler(),
2582 accessor.level(),
2583 accessor.index(),
2584 fe_index,
2585 std::integral_constant<int, structdim>());
2586 }
2587
2588 template <int dim, int spacedim, int structdim>
2589 static std::pair<unsigned int, unsigned int>
2590 process_object_range(dealii::DoFInvalidAccessor<structdim, dim, spacedim>,
2591 const unsigned int)
2592 {
2593 DEAL_II_ASSERT_UNREACHABLE();
2594
2595 return {0, 0};
2596 }
2597
2598
2599
2600 /**
2601 * Process all dofs of an object.
2602 *
2603 * The template argument `structdim` indicates the
2604 * dimensionality of the object on which we seek to know the DoF
2605 * index. For example, if `structdim==0`, then we are looking to
2606 * get a DoF index on a vertex of the indicated cell.
2607 */
2608 template <int dim,
2609 int spacedim,
2610 int structdim,
2611 typename DoFProcessor,
2612 typename DoFMapping>
2613 static DEAL_II_ALWAYS_INLINE void
2614 process_object(const DoFHandler<dim, spacedim> &dof_handler,
2615 const unsigned int obj_level,
2616 const unsigned int obj_index,
2617 const types::fe_index fe_index,
2618 const DoFMapping &mapping,
2619 const std::integral_constant<int, structdim> &dd,
2620 types::global_dof_index *&dof_indices_ptr,
2621 const DoFProcessor &process)
2622 {
2623 Assert(structdim == dim || obj_level == 0, ExcNotImplemented());
2624
2625 // determine range of dofs in global data structure
2626 const auto range =
2627 process_object_range(dof_handler, obj_level, obj_index, fe_index, dd);
2628 if (range.second == 0)
2629 return;
2630
2631 std::vector<types::global_dof_index> &object_dof_indices =
2632 dof_handler
2633 .object_dof_indices[structdim < dim ? 0 : obj_level][structdim];
2634 AssertIndexRange(range.first, object_dof_indices.size());
2635 types::global_dof_index *DEAL_II_RESTRICT stored_indices =
2636 object_dof_indices.data() + range.first;
2637
2638 // process dofs
2639 for (unsigned int i = 0; i < range.second; ++i)
2640 {
2641 process(
2642 stored_indices[(structdim == 0 || structdim == dim) ? i :
2643 mapping(i)],
2644 dof_indices_ptr);
2645 if (dof_indices_ptr != nullptr)
2646 ++dof_indices_ptr;
2647 }
2648 }
2649
2650
2651
2652 /**
2653 * Set the @p local_index-th degree of freedom corresponding to the
2654 * finite element specified by @p fe_index on the vertex with global
2655 * number @p vertex_index to @p global_index.
2656 *
2657 * The template argument `structdim` indicates the
2658 * dimensionality of the object on which we seek to know the DoF
2659 * index. For example, if `structdim==0`, then we are looking to
2660 * get a DoF index on a vertex of the indicated cell.
2661 */
2662 template <int dim, int spacedim, int structdim>
2663 static void
2664 set_dof_index(const DoFHandler<dim, spacedim> &dof_handler,
2665 const unsigned int obj_level,
2666 const unsigned int obj_index,
2667 const types::fe_index fe_index,
2668 const unsigned int local_index,
2669 const std::integral_constant<int, structdim> &dd,
2670 const types::global_dof_index global_index)
2671 {
2672 process_dof_index(dof_handler,
2673 obj_level,
2674 obj_index,
2675 fe_index,
2676 local_index,
2677 dd,
2678 global_index,
2679 [](auto &ptr, const auto &value) { ptr = value; });
2680 }
2681
2682
2683 /**
2684 * Get the @p local_index-th degree of freedom corresponding to the
2685 * finite element specified by @p fe_index on the vertex with global
2686 * number @p vertex_index to @p global_index.
2687 *
2688 * The template argument `structdim` indicates the
2689 * dimensionality of the object on which we seek to know the DoF
2690 * index. For example, if `structdim==0`, then we are looking to
2691 * get a DoF index on a vertex of the indicated cell.
2692 */
2693 template <int dim, int spacedim, int structdim>
2694 static types::global_dof_index
2695 get_dof_index(const DoFHandler<dim, spacedim> &dof_handler,
2696 const unsigned int obj_level,
2697 const unsigned int obj_index,
2698 const types::fe_index fe_index,
2699 const unsigned int local_index,
2700 const std::integral_constant<int, structdim> &dd)
2701 {
2702 types::global_dof_index global_index;
2703 process_dof_index(dof_handler,
2704 obj_level,
2705 obj_index,
2706 fe_index,
2707 local_index,
2708 dd,
2709 global_index,
2710 [](const auto &ptr, auto &value) { value = ptr; });
2711 return global_index;
2712 }
2713
2714
2715 template <int dim, int spacedim>
2716 static types::global_dof_index &
2717 mg_vertex_dof_index(DoFHandler<dim, spacedim> &dof_handler,
2718 const int level,
2719 const unsigned int vertex_index,
2720 const unsigned int i)
2721 {
2722 Assert(dof_handler.hp_capability_enabled == false,
2723 ExcMessage(
2724 "DoFHandler in hp-mode does not implement multilevel DoFs."));
2725
2726 return dof_handler.mg_vertex_dofs[vertex_index].access_index(
2727 level, i, dof_handler.get_fe().n_dofs_per_vertex());
2728 }
2729
2730
2731
2732 /**
2733 * Return the number of different finite elements that are active on a
2734 * given object such as a vertex, line, or cell.
2735 *
2736 * The template argument `structdim` indicates the
2737 * dimensionality of the object on which we seek to know the DoF
2738 * index. For example, if `structdim==0`, then we are looking to
2739 * get a DoF index on a vertex of the indicated cell.
2740 */
2741 template <int dim, int spacedim, int structdim>
2742 static unsigned int
2743 n_active_fe_indices(const DoFHandler<dim, spacedim> &dof_handler,
2744 const unsigned int obj_level,
2745 const unsigned int obj_index,
2746 const std::integral_constant<int, structdim> &)
2747 {
2748 (void)obj_level;
2749
2750 Assert(structdim == dim || obj_level == 0, ExcNotImplemented());
2751
2752 // 1) no hp used -> fe_index == 0
2753 if (dof_handler.hp_capability_enabled == false)
2754 return 1;
2755
2756 // 2) cell and hp is used -> there is only one fe_index
2757 if (structdim == dim)
2758 return 1;
2759
2760 // 3) general entity and hp is used
2761 AssertIndexRange(structdim, dof_handler.hp_object_fe_ptr.size());
2762 AssertIndexRange(obj_index + 1,
2763 dof_handler.hp_object_fe_ptr[structdim].size());
2764
2765 return dof_handler.hp_object_fe_ptr[structdim][obj_index + 1] -
2766 dof_handler.hp_object_fe_ptr[structdim][obj_index];
2767 }
2768
2769
2770
2771 /**
2772 * Return the FE index of the n-th finite element active on a given
2773 * object such as a vertex, line, or cell.
2774 *
2775 * The template argument `structdim` indicates the
2776 * dimensionality of the object on which we seek to know the DoF
2777 * index. For example, if `structdim==0`, then we are looking to
2778 * get a DoF index on a vertex of the indicated cell.
2779 */
2780 template <int dim, int spacedim, int structdim>
2781 static types::fe_index
2782 nth_active_fe_index(const DoFHandler<dim, spacedim> &dof_handler,
2783 const unsigned int obj_level,
2784 const unsigned int obj_index,
2785 const unsigned int local_index,
2786 const std::integral_constant<int, structdim> &)
2787 {
2788 Assert(structdim == dim || obj_level == 0, ExcNotImplemented());
2789
2790 // for cells only one active FE index available
2791 Assert(((structdim == dim) &&
2792 (local_index != DoFHandler<dim, spacedim>::default_fe_index)) ==
2793 false,
2794 ExcNotImplemented());
2795
2796 // 1) no hp used -> fe_index == 0
2797 if (dof_handler.hp_capability_enabled == false)
2798 return DoFHandler<dim, spacedim>::default_fe_index;
2799
2800 // 2) cell and hp is used -> there is only one fe_index
2801 if (structdim == dim)
2802 return dof_handler.hp_cell_active_fe_indices[obj_level][obj_index];
2803
2804 // 3) general entity and hp is used
2805 AssertIndexRange(structdim, dof_handler.hp_object_fe_indices.size());
2806 AssertIndexRange(structdim, dof_handler.hp_object_fe_ptr.size());
2807 AssertIndexRange(obj_index,
2808 dof_handler.hp_object_fe_ptr[structdim].size());
2809 AssertIndexRange(dof_handler.hp_object_fe_ptr[structdim][obj_index] +
2810 local_index,
2811 dof_handler.hp_object_fe_indices[structdim].size());
2812
2813 return dof_handler.hp_object_fe_indices
2814 [structdim]
2815 [dof_handler.hp_object_fe_ptr[structdim][obj_index] + local_index];
2816 }
2817
2818
2819
2820 /**
2821 * Returns all active FE indices on a given object such as a
2822 * vertex, line, or cell.
2823 *
2824 * The size of the returned set equals the number of finite elements that
2825 * are active on this vertex.
2826 *
2827 * The template argument `structdim` indicates the
2828 * dimensionality of the object on which we seek to know the DoF
2829 * index. For example, if `structdim==0`, then we are looking to
2830 * get a DoF index on a vertex of the indicated cell.
2831 */
2832 template <int dim, int spacedim, int structdim>
2833 static std::set<types::fe_index>
2834 get_active_fe_indices(const DoFHandler<dim, spacedim> &dof_handler,
2835 const unsigned int obj_level,
2836 const unsigned int obj_index,
2837 const std::integral_constant<int, structdim> &t)
2838 {
2839 Assert(structdim == dim || obj_level == 0, ExcNotImplemented());
2840
2841 // 1) no hp used -> fe_index == 0
2842 if (dof_handler.hp_capability_enabled == false)
2843 return {DoFHandler<dim, spacedim>::default_fe_index};
2844
2845 // 2) cell and hp is used -> there is only one fe_index
2846 if (structdim == dim)
2847 return {dof_handler.hp_cell_active_fe_indices[obj_level][obj_index]};
2848
2849 // 3) general entity and hp is used
2850 std::set<types::fe_index> active_fe_indices;
2851 for (unsigned int i = 0;
2852 i < n_active_fe_indices(dof_handler, obj_level, obj_index, t);
2853 ++i)
2854 active_fe_indices.insert(
2855 nth_active_fe_index(dof_handler, obj_level, obj_index, i, t));
2856 return active_fe_indices;
2857 }
2858
2859
2860
2861 template <int dim, int spacedim, int structdim>
2862 static bool
2863 fe_index_is_active(const DoFHandler<dim, spacedim> &dof_handler,
2864 const unsigned int obj_level,
2865 const unsigned int obj_index,
2866 const types::fe_index fe_index,
2867 const std::integral_constant<int, structdim> &)
2868 {
2869 Assert(structdim == dim || obj_level == 0, ExcNotImplemented());
2870
2871 // 1) no hp used -> fe_index == 0
2872 if (dof_handler.hp_capability_enabled == false)
2873 return (fe_index == DoFHandler<dim, spacedim>::default_fe_index);
2874
2875 // 2) cell and hp is used -> there is only one fe_index
2876 if (structdim == dim)
2877 return dof_handler.hp_cell_active_fe_indices[obj_level][obj_index] ==
2878 fe_index;
2879
2880 // 3) general entity and hp is used
2881 return std::find(
2882 dof_handler.hp_object_fe_indices[structdim].begin() +
2883 dof_handler.hp_object_fe_ptr[structdim][obj_index],
2884 dof_handler.hp_object_fe_indices[structdim].begin() +
2885 dof_handler.hp_object_fe_ptr[structdim][obj_index + 1],
2886 fe_index) !=
2887 (dof_handler.hp_object_fe_indices[structdim].begin() +
2888 dof_handler.hp_object_fe_ptr[structdim][obj_index + 1]);
2889 }
2890
2891
2892
2893 template <typename InputVector, typename ForwardIterator>
2894 static void
2895 extract_subvector_to(const InputVector &values,
2896 const types::global_dof_index *cache,
2897 const types::global_dof_index *cache_end,
2898 ForwardIterator local_values_begin)
2899 {
2900 values.extract_subvector_to(cache, cache_end, local_values_begin);
2901 }
2902
2903
2904
2905 #ifdef DEAL_II_WITH_TRILINOS
2906 static std::vector<unsigned int>
2907 sort_indices(const types::global_dof_index *v_begin,
2908 const types::global_dof_index *v_end)
2909 {
2910 // initialize original index locations
2911 std::vector<unsigned int> idx(v_end - v_begin);
2912 std::iota(idx.begin(), idx.end(), 0u);
2913
2914 // sort indices based on comparing values in v
2915 std::sort(idx.begin(),
2916 idx.end(),
2917 [&v_begin](unsigned int i1, unsigned int i2) {
2918 return *(v_begin + i1) < *(v_begin + i2);
2919 });
2920
2921 return idx;
2922 }
2923
2924
2925
2926 # ifdef DEAL_II_TRILINOS_WITH_TPETRA
2927 template <typename ForwardIterator, typename Number, typename MemorySpace>
2928 static void
2929 extract_subvector_to(
2930 const LinearAlgebra::TpetraWrappers::Vector<Number, MemorySpace>
2931 &values,
2932 const types::global_dof_index *cache_begin,
2933 const types::global_dof_index *cache_end,
2934 ForwardIterator local_values_begin)
2935 {
2936 std::vector<unsigned int> sorted_indices_pos =
2937 sort_indices(cache_begin, cache_end);
2938 const unsigned int cache_size = cache_end - cache_begin;
2939 std::vector<types::global_dof_index> cache_indices(cache_size);
2940 for (unsigned int i = 0; i < cache_size; ++i)
2941 cache_indices[i] = *(cache_begin + sorted_indices_pos[i]);
2942
2943 IndexSet index_set(cache_indices.back() + 1);
2944 index_set.add_indices(cache_indices.begin(), cache_indices.end());
2945 index_set.compress();
2946 LinearAlgebra::ReadWriteVector<Number> read_write_vector(index_set);
2947 read_write_vector.import_elements(values, VectorOperation::insert);
2948
2949 // Copy the elements from read_write_vector and reorder them.
2950 for (unsigned int i = 0; i < cache_size; ++i, ++local_values_begin)
2951 *local_values_begin = read_write_vector[sorted_indices_pos[i]];
2952 }
2953 # endif
2954
2955
2956
2957 template <typename ForwardIterator>
2958 static void
2959 extract_subvector_to(const LinearAlgebra::EpetraWrappers::Vector &values,
2960 const types::global_dof_index *cache_begin,
2961 const types::global_dof_index *cache_end,
2962 ForwardIterator local_values_begin)
2963 {
2964 std::vector<unsigned int> sorted_indices_pos =
2965 sort_indices(cache_begin, cache_end);
2966 const unsigned int cache_size = cache_end - cache_begin;
2967 std::vector<types::global_dof_index> cache_indices(cache_size);
2968 for (unsigned int i = 0; i < cache_size; ++i)
2969 cache_indices[i] = *(cache_begin + sorted_indices_pos[i]);
2970
2971 IndexSet index_set(cache_indices.back() + 1);
2972 index_set.add_indices(cache_indices.begin(), cache_indices.end());
2973 index_set.compress();
2974 LinearAlgebra::ReadWriteVector<double> read_write_vector(index_set);
2975 read_write_vector.import_elements(values, VectorOperation::insert);
2976
2977 // Copy the elements from read_write_vector and reorder them.
2978 for (unsigned int i = 0; i < cache_size; ++i, ++local_values_begin)
2979 *local_values_begin = read_write_vector[sorted_indices_pos[i]];
2980 }
2981 #endif
2982
2983 /**
2984 * Loop over all degrees of freedom of the object described by the
2985 * provided @p accessor and @p fe_index and count them.
2986 */
2987 template <int dim, int spacedim, bool level_dof_access, int structdim>
2988 static unsigned int
2989 n_dof_indices(
2990 const dealii::DoFAccessor<structdim, dim, spacedim, level_dof_access>
2991 &accessor,
2992 const types::fe_index fe_index_,
2993 const bool count_level_dofs)
2994 {
2995 // note: we cannot rely on the template parameter level_dof_access here,
2996 // since the function get_mg_dof_indices()/set_mg_dof_indices() can be
2997 // called even if level_dof_access==false.
2998 if (count_level_dofs)
2999 {
3000 const auto &fe = accessor.get_fe(fe_index_);
3001
3002 const unsigned int //
3003 dofs_per_vertex = fe.n_dofs_per_vertex(), //
3004 dofs_per_line = fe.n_dofs_per_line(), //
3005 dofs_per_quad = fe.n_dofs_per_quad(0 /*dummy*/), //
3006 dofs_per_hex = fe.n_dofs_per_hex(); //
3007
3008 unsigned int index = 0;
3009
3010 // 1) VERTEX dofs
3011 index += dofs_per_vertex * accessor.n_vertices();
3012
3013 // 2) LINE dofs
3014 if (structdim == 2 || structdim == 3)
3015 index += dofs_per_line * accessor.n_lines();
3016
3017 // 3) FACE dofs
3018 if (structdim == 3)
3019 index += dofs_per_quad * accessor.n_faces();
3020
3021 // 4) INNER dofs
3022 const unsigned int interior_dofs =
3023 structdim == 1 ? dofs_per_line :
3024 (structdim == 2 ? dofs_per_quad : dofs_per_hex);
3025
3026 index += interior_dofs;
3027
3028 return index;
3029 }
3030 else
3031 {
3032 const auto fe_index =
3033 internal::DoFAccessorImplementation::get_fe_index_or_default(
3034 accessor, fe_index_);
3035
3036 unsigned int index = 0;
3037
3038 // 1) VERTEX dofs
3039 for (const auto vertex : accessor.vertex_indices())
3040 index += process_object_range(accessor.get_dof_handler(),
3041 0,
3042 accessor.vertex_index(vertex),
3043 fe_index,
3044 std::integral_constant<int, 0>())
3045 .second;
3046
3047 // 2) LINE dofs
3048 if (structdim == 2 || structdim == 3)
3049 for (const auto line : accessor.line_indices())
3050 index +=
3051 process_object_range(*accessor.line(line), fe_index).second;
3052
3053 // 3) FACE dofs
3054 if (structdim == 3)
3055 for (const auto face : accessor.face_indices())
3056 index +=
3057 process_object_range(*accessor.quad(face), fe_index).second;
3058
3059 // 4) INNER dofs
3060 index += process_object_range(accessor, fe_index).second;
3061
3062 return index;
3063 }
3064 }
3065
3066
3067
3068 // The next few internal helper functions are needed to support various
3069 // DoFIndicesType kinds, e.g. actual vectors of DoFIndices or empty
3070 // types that we use when we only want to work on the internally stored
3071 // DoFs and never extract any number.
3072 template <typename ArrayType>
3073 static unsigned int
3074 get_array_length(const ArrayType &array)
3075 {
3076 return array.size();
3077 }
3078
3079 static unsigned int
3080 get_array_length(const std::tuple<> &)
3081 {
3082 return 0;
3083 }
3084
3085 template <typename ArrayType>
3086 static types::global_dof_index *
3087 get_array_ptr(const ArrayType &array)
3088 {
3089 return const_cast<types::global_dof_index *>(array.data());
3090 }
3091
3092 static types::global_dof_index *
3093 get_array_ptr(const std::tuple<> &)
3094 {
3095 return nullptr;
3096 }
3097
3098
3099
3100 /**
3101 * Loop over all degrees of freedom of the object described by the
3102 * provided @p accessor and @p fe_index and perform the static functions
3103 * provided by DoFOperation (set/get) on these.
3104 */
3105 template <int dim,
3106 int spacedim,
3107 bool level_dof_access,
3108 int structdim,
3109 typename DoFIndicesType,
3110 typename DoFOperation,
3111 typename DoFProcessor>
3112 static void
3113 process_dof_indices(
3114 const dealii::DoFAccessor<structdim, dim, spacedim, level_dof_access>
3115 &accessor,
3116 const DoFIndicesType &const_dof_indices,
3117 const types::fe_index fe_index_,
3118 const DoFOperation &dof_operation,
3119 const DoFProcessor &dof_processor,
3120 const bool count_level_dofs)
3121 {
3122 const types::fe_index fe_index =
3123 internal::DoFAccessorImplementation::get_fe_index_or_default(
3124 accessor, fe_index_);
3125
3126 // we cannot rely on the template parameter level_dof_access here, since
3127 // the function get_mg_dof_indices()/set_mg_dof_indices() can be called
3128 // even if level_dof_access==false.
3129 (void)count_level_dofs;
3130
3131 const auto &fe = accessor.get_fe(fe_index);
3132
3133 // we want to pass in rvalue 'std::tuple<>' types as `DoFIndicesType`,
3134 // but we need non-const references for std::vector<> types, so get in
3135 // a const reference here and immediately cast the constness away -
3136 // note that any use of the dereferenced invalid type will result in a
3137 // segfault
3138 types::global_dof_index *dof_indices_ptr =
3139 get_array_ptr(const_dof_indices);
3140 types::global_dof_index *end_dof_indices =
3141 dof_indices_ptr + get_array_length(const_dof_indices);
3142
3143 // 1) VERTEX dofs, only step into the functions if we actually have
3144 // DoFs on them
3145 if (fe.n_dofs_per_vertex() > 0)
3146 for (const auto vertex : accessor.vertex_indices())
3147 dof_operation.process_vertex_dofs(*accessor.dof_handler,
3148 accessor.vertex_index(vertex),
3149 fe_index,
3150 dof_indices_ptr,
3151 dof_processor);
3152
3153 // 2) copy dof numbers from the LINE, accounting for the possibility of
3154 // reversed line orientations.
3155 if (structdim > 1 && fe.n_dofs_per_line() > 0)
3156 {
3157 const auto line_indices = internal::TriaAccessorImplementation::
3158 Implementation::get_line_indices_of_cell(accessor);
3159 const auto line_orientations =
3160 internal::TriaAccessorImplementation::Implementation::
3161 get_line_orientations_of_cell(accessor);
3162
3163 for (const auto line : accessor.line_indices())
3164 {
3165 const auto line_orientation = line_orientations[line];
3166 if (line_orientation == numbers::default_geometric_orientation)
3167 dof_operation.process_dofs(
3168 accessor.get_dof_handler(),
3169 0,
3170 line_indices[line],
3171 fe_index,
3172 [](const auto d) { return d; },
3173 std::integral_constant<int, 1>(),
3174 dof_indices_ptr,
3175 dof_processor);
3176 else
3177 {
3178 Assert(line_orientation ==
3179 numbers::reverse_line_orientation,
3180 ExcInternalError());
3181 dof_operation.process_dofs(
3182 accessor.get_dof_handler(),
3183 0,
3184 line_indices[line],
3185 fe_index,
3186 [&fe, line_orientation](const auto d) {
3187 return fe.adjust_line_dof_index_for_line_orientation(
3188 d, line_orientation);
3189 },
3190 std::integral_constant<int, 1>(),
3191 dof_indices_ptr,
3192 dof_processor);
3193 }
3194 }
3195 }
3196
3197 // 3) copy dof numbers from the QUAD (i.e., 3d faces). Like lines we
3198 // only adjust dof indices (which has some cost) if we are not in the
3199 // default orientation.
3200 if (structdim == 3 && fe.max_dofs_per_quad() > 0)
3201 for (const auto face_no : accessor.face_indices())
3202 {
3203 const auto combined_orientation =
3204 accessor.combined_face_orientation(face_no);
3205 const unsigned int quad_index = accessor.quad_index(face_no);
3206 if (combined_orientation ==
3207 numbers::default_geometric_orientation)
3208 dof_operation.process_dofs(
3209 accessor.get_dof_handler(),
3210 0,
3211 quad_index,
3212 fe_index,
3213 [](const auto d) { return d; },
3214 std::integral_constant<int, 2>(),
3215 dof_indices_ptr,
3216 dof_processor);
3217 else
3218 dof_operation.process_dofs(
3219 accessor.get_dof_handler(),
3220 0,
3221 quad_index,
3222 fe_index,
3223 [&](const auto d) {
3224 return fe.adjust_quad_dof_index_for_face_orientation(
3225 d, face_no, combined_orientation);
3226 },
3227 std::integral_constant<int, 2>(),
3228 dof_indices_ptr,
3229 dof_processor);
3230 }
3231
3232 // 4) INNER dofs (i.e., line dofs in 1d, quad dofs in 2d, or hex dofs in
3233 // 3d) - here we need to make sure that the shortcut to not run the
3234 // function does not miss the faces of wedge and pyramid elements where
3235 // n_dofs_per_object might not return the largest possible value
3236 if (((dim == 3 && structdim == 2) ?
3237 fe.max_dofs_per_quad() :
3238 fe.template n_dofs_per_object<structdim>()) > 0)
3239 dof_operation.process_dofs(
3240 accessor.get_dof_handler(),
3241 accessor.level(),
3242 accessor.index(),
3243 fe_index,
3244 [&](const auto d) { return d; },
3245 std::integral_constant<int, structdim>(),
3246 dof_indices_ptr,
3247 dof_processor);
3248
3249 if (dof_indices_ptr != nullptr)
3250 {
3251 AssertDimension(n_dof_indices(accessor, fe_index, count_level_dofs),
3252 dof_indices_ptr - get_array_ptr(const_dof_indices));
3253 }
3254
3255 // PM: This is a part that should not be reached since it indicates that
3256 // an object (and/or its subobjects) is not active. However,
3257 // unfortunately this function is called by
3258 // DoFTools::set_periodicity_constraints() indirectly by
3259 // get_dof_indices() also for artificial faces to determine if a face
3260 // is artificial.
3261 types::global_dof_index invalid_index = numbers::invalid_dof_index;
3262 for (; dof_indices_ptr < end_dof_indices; ++dof_indices_ptr)
3263 dof_processor(invalid_index, dof_indices_ptr);
3264 }
3265
3266
3267
3268 /**
3269 * An internal struct encapsulating the task of getting (vertex)
3270 * DoF indices.
3271 */
3272 template <int dim, int spacedim>
3273 struct DoFIndexProcessor
3274 {
3275 /**
3276 * Return vertex DoF indices.
3277 */
3278 template <typename DoFProcessor>
3279 DEAL_II_ALWAYS_INLINE void
3280 process_vertex_dofs(DoFHandler<dim, spacedim> &dof_handler,
3281 const unsigned int vertex_index,
3282 const types::fe_index fe_index,
3283 types::global_dof_index *&dof_indices_ptr,
3284 const DoFProcessor &dof_processor) const
3285 {
3286 process_object(
3287 dof_handler,
3288 0,
3289 vertex_index,
3290 fe_index,
3291 [](const auto d) {
3292 DEAL_II_ASSERT_UNREACHABLE();
3293 return d;
3294 },
3295 std::integral_constant<int, 0>(),
3296 dof_indices_ptr,
3297 dof_processor);
3298 }
3299
3300 /**
3301 * Return DoF indices for lines, quads, and inner degrees of freedom.
3302 */
3303 template <int structdim, typename DoFMapping, typename DoFProcessor>
3304 DEAL_II_ALWAYS_INLINE void
3305 process_dofs(const DoFHandler<dim, spacedim> &dof_handler,
3306 const unsigned int obj_level,
3307 const unsigned int obj_index,
3308 const types::fe_index fe_index,
3309 const DoFMapping &mapping,
3310 const std::integral_constant<int, structdim>,
3311 types::global_dof_index *&dof_indices_ptr,
3312 const DoFProcessor &dof_processor) const
3313 {
3314 process_object(
3315 dof_handler,
3316 obj_level,
3317 obj_index,
3318 fe_index,
3319 mapping,
3320 std::integral_constant<int, std::min(structdim, dim)>(),
3321 dof_indices_ptr,
3322 dof_processor);
3323 }
3324 };
3325
3326
3327
3328 /**
3329 * An internal struct encapsulating the task of getting level (vertex)
3330 * DoF indices.
3331 */
3332 template <int dim, int spacedim>
3333 struct MGDoFIndexProcessor
3334 {
3335 /**
3336 * Constructor.
3337 */
3338 MGDoFIndexProcessor(const unsigned int level)
3339 : level(level)
3340 {}
3341
3342 /**
3343 * Return vertex DoF indices.
3344 */
3345 template <typename DoFProcessor>
3346 DEAL_II_ALWAYS_INLINE void
3347 process_vertex_dofs(DoFHandler<dim, spacedim> &dof_handler,
3348 const unsigned int vertex_index,
3349 const types::fe_index,
3350 types::global_dof_index *&dof_indices_ptr,
3351 const DoFProcessor &dof_processor) const
3352 {
3353 const unsigned int n_indices =
3354 dof_handler.get_fe(0).template n_dofs_per_object<0>();
3355 types::global_dof_index *stored_indices =
3356 &dof_handler.mg_vertex_dofs[vertex_index].access_index(level,
3357 0,
3358 n_indices);
3359 for (unsigned int d = 0; d < n_indices; ++d, ++dof_indices_ptr)
3360 dof_processor(stored_indices[d], dof_indices_ptr);
3361 }
3362
3363 /**
3364 * Return DoF indices for lines, quads, and inner degrees of freedom.
3365 */
3366 template <int structdim, typename DoFMapping, typename DoFProcessor>
3367 DEAL_II_ALWAYS_INLINE void
3368 process_dofs(const DoFHandler<dim, spacedim> &dof_handler,
3369 const unsigned int,
3370 const unsigned int obj_index,
3371 const types::fe_index fe_index,
3372 const DoFMapping &mapping,
3373 const std::integral_constant<int, structdim>,
3374 types::global_dof_index *&dof_indices_ptr,
3375 const DoFProcessor &dof_processor) const
3376 {
3377 const unsigned int n_indices =
3378 dof_handler.get_fe(0).template n_dofs_per_object<structdim>();
3379 types::global_dof_index *stored_indices = &get_mg_dof_index(
3380 dof_handler,
3381 dof_handler.mg_levels[level],
3382 dof_handler.mg_faces,
3383 obj_index,
3384 fe_index,
3385 0,
3386 std::integral_constant<int, std::min(structdim, dim)>());
3387 for (unsigned int d = 0; d < n_indices; ++d, ++dof_indices_ptr)
3388 dof_processor(stored_indices[structdim < dim ? mapping(d) : d],
3389 dof_indices_ptr);
3390 }
3391
3392 private:
3393 const unsigned int level;
3394 };
3395
3396
3397
3398 template <int dim, int spacedim, bool level_dof_access, int structdim>
3399 static void
3400 get_dof_indices(
3401 const dealii::DoFAccessor<structdim, dim, spacedim, level_dof_access>
3402 &accessor,
3403 std::vector<types::global_dof_index> &dof_indices,
3404 const types::fe_index fe_index)
3405 {
3406 process_dof_indices(
3407 accessor,
3408 dof_indices,
3409 fe_index,
3410 DoFIndexProcessor<dim, spacedim>(),
3411 [](auto stored_index, auto dof_ptr) { *dof_ptr = stored_index; },
3412 false);
3413 }
3414
3415
3416
3417 template <int dim, int spacedim, bool level_dof_access, int structdim>
3418 static void
3419 set_dof_indices(
3420 const dealii::DoFAccessor<structdim, dim, spacedim, level_dof_access>
3421 &accessor,
3422 const std::vector<types::global_dof_index> &dof_indices,
3423 const types::fe_index fe_index)
3424 {
3425 // Note: this function is as general as `get_dof_indices()`. This
3426 // assert is placed here since it is currently only used by the
3427 // function DoFCellAccessor::set_dof_indices(), which is called by
3428 // internal::DoFHandlerImplementation::Policy::Implementation::distribute_dofs().
3429 // In the case of new use cases, this assert can be removed.
3430 Assert(
3431 dim == structdim,
3432 ExcMessage(
3433 "This function is intended to be used for DoFCellAccessor, i.e., "
3434 "dimension == structdim."));
3435
3436 process_dof_indices(
3437 accessor,
3438 dof_indices,
3439 fe_index,
3440 DoFIndexProcessor<dim, spacedim>(),
3441 [](auto &stored_index, auto dof_ptr) { stored_index = *dof_ptr; },
3442 false);
3443 }
3444
3445
3446
3447 template <int dim, int spacedim, bool level_dof_access, int structdim>
3448 static void
3449 get_mg_dof_indices(
3450 const dealii::DoFAccessor<structdim, dim, spacedim, level_dof_access>
3451 &accessor,
3452 const int level,
3453 std::vector<types::global_dof_index> &dof_indices,
3454 const types::fe_index fe_index)
3455 {
3456 Assert((fe_index == DoFHandler<dim, spacedim>::default_fe_index),
3457 ExcMessage("MG DoF indices cannot be queried in hp case"));
3458 process_dof_indices(
3459 accessor,
3460 dof_indices,
3461 fe_index,
3462 MGDoFIndexProcessor<dim, spacedim>(level),
3463 [](auto stored_index, auto dof_ptr) { *dof_ptr = stored_index; },
3464 true);
3465 }
3466
3467
3468
3469 template <int dim, int spacedim, bool level_dof_access, int structdim>
3470 static void
3471 set_mg_dof_indices(
3472 const dealii::DoFAccessor<structdim, dim, spacedim, level_dof_access>
3473 &accessor,
3474 const int level,
3475 const std::vector<types::global_dof_index> &dof_indices,
3476 const types::fe_index fe_index)
3477 {
3478 Assert((fe_index == DoFHandler<dim, spacedim>::default_fe_index),
3479 ExcMessage("MG DoF indices cannot be queried in hp case"));
3480
3481 // Note: this function is as general as `get_mg_dof_indices()`. This
3482 // assert is placed here since it is currently only used by the
3483 // function DoFCellAccessor::set_mg_dof_indices(), which is called by
3484 // internal::DoFHandlerImplementation::Policy::Implementation::distribute_mg_dofs().
3485 // In the case of new use cases, this assert can be removed.
3486 Assert(dim == structdim,
3487 ExcMessage("This function is intended to be used for "
3488 "DoFCellAccessor, i.e., dimension == structdim."));
3489
3490 process_dof_indices(
3491 accessor,
3492 dof_indices,
3493 fe_index,
3494 MGDoFIndexProcessor<dim, spacedim>(level),
3495 [](auto &stored_index, auto dof_ptr) { stored_index = *dof_ptr; },
3496 true);
3497 }
3498
3499
3500
3501 template <int dim, int spacedim>
3502 static types::global_dof_index &
3503 get_mg_dof_index(
3504 const DoFHandler<dim, spacedim> &dof_handler,
3505 const std::unique_ptr<internal::DoFHandlerImplementation::DoFLevel<dim>>
3506 &mg_level,
3507 const std::unique_ptr<internal::DoFHandlerImplementation::DoFFaces<dim>>
3508 &,
3509 const unsigned int obj_index,
3510 const types::fe_index fe_index,
3511 const unsigned int local_index,
3512 const std::integral_constant<int, dim>)
3513 {
3514 Assert(dof_handler.hp_capability_enabled == false,
3515 (typename DoFHandler<dim, spacedim>::ExcNotImplementedWithHP()));
3516
3517 return mg_level->dof_object.access_dof_index(
3518 static_cast<const DoFHandler<dim, spacedim> &>(dof_handler),
3519 obj_index,
3520 fe_index,
3521 local_index);
3522 }
3523
3524
3525
3526 template <int dim, int spacedim, std::enable_if_t<(dim > 1), int> = 0>
3527 static types::global_dof_index &
3528 get_mg_dof_index(
3529 const DoFHandler<dim, spacedim> &dof_handler,
3530 const std::unique_ptr<internal::DoFHandlerImplementation::DoFLevel<dim>>
3531 &,
3532 const std::unique_ptr<internal::DoFHandlerImplementation::DoFFaces<dim>>
3533 &mg_faces,
3534 const unsigned int obj_index,
3535 const types::fe_index fe_index,
3536 const unsigned int local_index,
3537 const std::integral_constant<int, 1>)
3538 {
3539 return mg_faces->lines.access_dof_index(
3540 static_cast<const DoFHandler<dim, spacedim> &>(dof_handler),
3541 obj_index,
3542 fe_index,
3543 local_index);
3544 }
3545
3546
3547
3548 template <int spacedim>
3549 static types::global_dof_index &
3550 get_mg_dof_index(
3551 const DoFHandler<3, spacedim> &dof_handler,
3552 const std::unique_ptr<internal::DoFHandlerImplementation::DoFLevel<3>>
3553 &,
3554 const std::unique_ptr<internal::DoFHandlerImplementation::DoFFaces<3>>
3555 &mg_faces,
3556 const unsigned int obj_index,
3557 const types::fe_index fe_index,
3558 const unsigned int local_index,
3559 const std::integral_constant<int, 2>)
3560 {
3561 Assert(dof_handler.hp_capability_enabled == false,
3562 (typename DoFHandler<3, spacedim>::ExcNotImplementedWithHP()));
3563 return mg_faces->quads.access_dof_index(
3564 static_cast<const DoFHandler<3, spacedim> &>(dof_handler),
3565 obj_index,
3566 fe_index,
3567 local_index);
3568 }
3569 };
3570
3571
3572
3573 template <int dim, int spacedim, bool level_dof_access>
3574 void
3575 get_cell_dof_indices(
3576 const dealii::DoFCellAccessor<dim, spacedim, level_dof_access> &accessor,
3577 Implementation::dof_index_vector_type &dof_indices,
3578 const unsigned int fe_index);
3579 } // namespace DoFAccessorImplementation
3580 } // namespace internal
3581
3582
3583
3584 template <int structdim, int dim, int spacedim, bool level_dof_access>
3585 inline types::global_dof_index
3586 DoFAccessor<structdim, dim, spacedim, level_dof_access>::dof_index(
3587 const unsigned int i,
3588 const types::fe_index fe_index_) const
3589 {
3590 const auto fe_index =
3591 internal::DoFAccessorImplementation::get_fe_index_or_default(*this,
3592 fe_index_);
3593
3594 // access the respective DoF
3595 return dealii::internal::DoFAccessorImplementation::Implementation::
3596 get_dof_index(*this->dof_handler,
3597 this->level(),
3598 this->index(),
3599 fe_index,
3600 i,
3601 std::integral_constant<int, structdim>());
3602 }
3603
3604
3605 template <int structdim, int dim, int spacedim, bool level_dof_access>
3606 inline types::global_dof_index
3607 DoFAccessor<structdim, dim, spacedim, level_dof_access>::mg_dof_index(
3608 const int level,
3609 const unsigned int i) const
3610 {
3611 return internal::DoFAccessorImplementation::Implementation::get_mg_dof_index(
3612 *this->dof_handler,
3613 this->dof_handler->mg_levels[level],
3614 this->dof_handler->mg_faces,
3615 this->index(),
3616 0,
3617 i,
3618 std::integral_constant<int, structdim>());
3619 }
3620
3621
3622 template <int structdim, int dim, int spacedim, bool level_dof_access>
3623 inline void
3624 DoFAccessor<structdim, dim, spacedim, level_dof_access>::set_dof_index(
3625 const unsigned int i,
3626 const types::global_dof_index index,
3627 const types::fe_index fe_index_) const
3628 {
3629 const auto fe_index =
3630 internal::DoFAccessorImplementation::get_fe_index_or_default(*this,
3631 fe_index_);
3632
3633 // access the respective DoF
3634 dealii::internal::DoFAccessorImplementation::Implementation::set_dof_index(
3635 *this->dof_handler,
3636 this->level(),
3637 this->index(),
3638 fe_index,
3639 i,
3640 std::integral_constant<int, structdim>(),
3641 index);
3642 }
3643
3644
3645
3646 template <int structdim, int dim, int spacedim, bool level_dof_access>
3647 inline void
3648 DoFAccessor<structdim, dim, spacedim, level_dof_access>::set_mg_dof_index(
3649 const int level,
3650 const unsigned int i,
3651 const types::global_dof_index index) const
3652 {
3653 internal::DoFAccessorImplementation::Implementation::get_mg_dof_index(
3654 *this->dof_handler,
3655 this->dof_handler->mg_levels[level],
3656 this->dof_handler->mg_faces,
3657 this->index(),
3658 0,
3659 i,
3660 std::integral_constant<int, structdim>()) = index;
3661 }
3662
3663
3664
3665 template <int structdim, int dim, int spacedim, bool level_dof_access>
3666 inline unsigned int
3667 DoFAccessor<structdim, dim, spacedim, level_dof_access>::n_active_fe_indices()
3668 const
3669 {
3670 // access the respective DoF
3671 return dealii::internal::DoFAccessorImplementation::Implementation::
3672 n_active_fe_indices(*this->dof_handler,
3673 this->level(),
3674 this->index(),
3675 std::integral_constant<int, structdim>());
3676 }
3677
3678
3679
3680 template <int structdim, int dim, int spacedim, bool level_dof_access>
3681 inline types::fe_index
3682 DoFAccessor<structdim, dim, spacedim, level_dof_access>::nth_active_fe_index(
3683 const unsigned int n) const
3684 {
3685 // access the respective DoF
3686 return dealii::internal::DoFAccessorImplementation::Implementation::
3687 nth_active_fe_index(*this->dof_handler,
3688 this->level(),
3689 this->index(),
3690 n,
3691 std::integral_constant<int, structdim>());
3692 }
3693
3694
3695
3696 template <int structdim, int dim, int spacedim, bool level_dof_access>
3697 inline std::set<types::fe_index>
3698 DoFAccessor<structdim, dim, spacedim, level_dof_access>::get_active_fe_indices()
3699 const
3700 {
3701 std::set<types::fe_index> active_fe_indices;
3702 for (unsigned int i = 0; i < n_active_fe_indices(); ++i)
3703 active_fe_indices.insert(nth_active_fe_index(i));
3704 return active_fe_indices;
3705 }
3706
3707
3708
3709 template <int structdim, int dim, int spacedim, bool level_dof_access>
3710 inline bool
3711 DoFAccessor<structdim, dim, spacedim, level_dof_access>::fe_index_is_active(
3712 const types::fe_index fe_index) const
3713 {
3714 // access the respective DoF
3715 return dealii::internal::DoFAccessorImplementation::Implementation::
3716 fe_index_is_active(*this->dof_handler,
3717 this->level(),
3718 this->index(),
3719 fe_index,
3720 std::integral_constant<int, structdim>());
3721 }
3722
3723
3724
3725 template <int structdim, int dim, int spacedim, bool level_dof_access>
3726 inline types::global_dof_index
3727 DoFAccessor<structdim, dim, spacedim, level_dof_access>::vertex_dof_index(
3728 const unsigned int vertex,
3729 const unsigned int i,
3730 const types::fe_index fe_index_) const
3731 {
3732 const types::fe_index fe_index =
3733 (((this->dof_handler->hp_capability_enabled == false) &&
3734 (fe_index_ == numbers::invalid_fe_index)) ?
3735 // No hp enabled, and the argument is at its default value -> we
3736 // can translate to the default active fe index
3737 DoFHandler<dim, spacedim>::default_fe_index :
3738 // Otherwise: If anything other than the default is provided by
3739 // the caller, then we should take just that. As an exception, if
3740 // we are on a cell (rather than a face/edge/vertex), then we know
3741 // that there is only one active fe index on this cell and we can
3742 // use that:
3743 ((dim == structdim) && (fe_index_ == numbers::invalid_fe_index) ?
3744 this->nth_active_fe_index(0) :
3745 fe_index_));
3746
3747 return dealii::internal::DoFAccessorImplementation::Implementation::
3748 get_dof_index(*this->dof_handler,
3749 0,
3750 this->vertex_index(vertex),
3751 fe_index,
3752 i,
3753 std::integral_constant<int, 0>());
3754 }
3755
3756
3757 template <int structdim, int dim, int spacedim, bool level_dof_access>
3758 inline types::global_dof_index
3759 DoFAccessor<structdim, dim, spacedim, level_dof_access>::mg_vertex_dof_index(
3760 const int level,
3761 const unsigned int vertex,
3762 const unsigned int i,
3763 const types::fe_index fe_index_) const
3764 {
3765 const auto fe_index =
3766 internal::DoFAccessorImplementation::get_fe_index_or_default(*this,
3767 fe_index_);
3768 (void)fe_index;
3769 Assert(this->dof_handler != nullptr, ExcInvalidObject());
3770 Assert(this->dof_handler->mg_vertex_dofs.size() > 0,
3771 ExcMessage("Multigrid DoF indices can only be accessed after "
3772 "DoFHandler::distribute_mg_dofs() has been called!"));
3773 AssertIndexRange(vertex, this->n_vertices());
3774 AssertIndexRange(i, this->dof_handler->get_fe(fe_index).n_dofs_per_vertex());
3775
3776 Assert(dof_handler->hp_capability_enabled == false,
3777 ExcMessage(
3778 "DoFHandler in hp-mode does not implement multilevel DoFs."));
3779
3780 return this->dof_handler->mg_vertex_dofs[this->vertex_index(vertex)]
3781 .access_index(level, i, this->dof_handler->get_fe().n_dofs_per_vertex());
3782 }
3783
3784
3785
3786 template <int structdim, int dim, int spacedim, bool level_dof_access>
3787 inline void
3788 DoFAccessor<structdim, dim, spacedim, level_dof_access>::
3789 set_mg_vertex_dof_index(const int level,
3790 const unsigned int vertex,
3791 const unsigned int i,
3792 const types::global_dof_index index,
3793 const types::fe_index fe_index_) const
3794 {
3795 const auto fe_index =
3796 internal::DoFAccessorImplementation::get_fe_index_or_default(*this,
3797 fe_index_);
3798 (void)fe_index;
3799 Assert(this->dof_handler != nullptr, ExcInvalidObject());
3800 AssertIndexRange(vertex, this->n_vertices());
3801 AssertIndexRange(i, this->dof_handler->get_fe(fe_index).n_dofs_per_vertex());
3802
3803 Assert(dof_handler->hp_capability_enabled == false,
3804 ExcMessage(
3805 "DoFHandler in hp-mode does not implement multilevel DoFs."));
3806
3807 this->dof_handler->mg_vertex_dofs[this->vertex_index(vertex)].access_index(
3808 level, i, this->dof_handler->get_fe().n_dofs_per_vertex()) = index;
3809 }
3810
3811
3812
3813 template <int structdim, int dim, int spacedim, bool level_dof_access>
3814 inline const FiniteElement<dim, spacedim> &
3815 DoFAccessor<structdim, dim, spacedim, level_dof_access>::get_fe(
3816 const types::fe_index fe_index) const
3817 {
3818 Assert(fe_index_is_active(fe_index) == true,
3819 ExcMessage("This function can only be called for active FE indices"));
3820
3821 return this->dof_handler->get_fe(fe_index);
3822 }
3823
3824
3825
3826 template <int structdim, int dim, int spacedim, bool level_dof_access>
3827 inline typename dealii::internal::DoFHandlerImplementation::
3828 Iterators<dim, spacedim, level_dof_access>::line_iterator
3829 DoFAccessor<structdim, dim, spacedim, level_dof_access>::line(
3830 const unsigned int i) const
3831 {
3832 // if we are asking for a particular line and this object refers to
3833 // a line, then the only valid index is i==0 and we should return
3834 // *this
3835 if (structdim == 1)
3836 {
3837 Assert(i == 0,
3838 ExcMessage("You can only ask for line zero if the "
3839 "current object is a line itself."));
3840 return typename dealii::internal::DoFHandlerImplementation::
3841 Iterators<dim, spacedim, level_dof_access>::cell_iterator(
3842 &this->get_triangulation(),
3843 this->level(),
3844 this->index(),
3845 &this->get_dof_handler());
3846 }
3847
3848 // otherwise we need to be in structdim>=2
3849 Assert(structdim > 1, ExcImpossibleInDim(structdim));
3850 Assert(dim > 1, ExcImpossibleInDim(dim));
3851
3852 // checking of 'i' happens in line_index(i)
3853 return typename dealii::internal::DoFHandlerImplementation::
3854 Iterators<dim, spacedim, level_dof_access>::line_iterator(
3855 this->tria,
3856 0, // only sub-objects are allowed, which have no level
3857 this->line_index(i),
3858 this->dof_handler);
3859 }
3860
3861
3862 template <int structdim, int dim, int spacedim, bool level_dof_access>
3863 inline typename dealii::internal::DoFHandlerImplementation::
3864 Iterators<dim, spacedim, level_dof_access>::quad_iterator
3865 DoFAccessor<structdim, dim, spacedim, level_dof_access>::quad(
3866 const unsigned int i) const
3867 {
3868 // if we are asking for a
3869 // particular quad and this object
3870 // refers to a quad, then the only
3871 // valid index is i==0 and we
3872 // should return *this
3873 if (structdim == 2)
3874 {
3875 Assert(i == 0,
3876 ExcMessage("You can only ask for quad zero if the "
3877 "current object is a quad itself."));
3878 return typename dealii::internal::DoFHandlerImplementation::
3879 Iterators<dim, spacedim>::cell_iterator(&this->get_triangulation(),
3880 this->level(),
3881 this->index(),
3882 &this->get_dof_handler());
3883 }
3884
3885 // otherwise we need to be in structdim>=3
3886 Assert(structdim > 2, ExcImpossibleInDim(structdim));
3887 Assert(dim > 2, ExcImpossibleInDim(dim));
3888
3889 // checking of 'i' happens in quad_index(i)
3890 return typename dealii::internal::DoFHandlerImplementation::
3891 Iterators<dim, spacedim, level_dof_access>::quad_iterator(
3892 this->tria,
3893 0, // only sub-objects are allowed, which have no level
3894 this->quad_index(i),
3895 this->dof_handler);
3896 }
3897
3898
3899 /*----------------- Functions: DoFAccessor<0,1,spacedim> --------------------*/
3900
3901
3902 template <int spacedim, bool level_dof_access>
3903 inline DoFAccessor<0, 1, spacedim, level_dof_access>::DoFAccessor()
3904 {
3905 Assert(false, ExcInvalidObject());
3906 }
3907
3908
3909
3910 template <int spacedim, bool level_dof_access>
3911 inline DoFAccessor<0, 1, spacedim, level_dof_access>::DoFAccessor(
3912 const Triangulation<1, spacedim> *tria,
3913 const typename TriaAccessor<0, 1, spacedim>::VertexKind vertex_kind,
3914 const unsigned int vertex_index,
3915 const DoFHandler<1, spacedim> *dof_handler)
3916 : BaseClass(tria, vertex_kind, vertex_index)
3917 , dof_handler(const_cast<DoFHandler<1, spacedim> *>(dof_handler))
3918 {}
3919
3920
3921
3922 template <int spacedim, bool level_dof_access>
3923 inline DoFAccessor<0, 1, spacedim, level_dof_access>::DoFAccessor(
3924 const Triangulation<1, spacedim> *tria,
3925 const int level,
3926 const int index,
3927 const DoFHandler<1, spacedim> *dof_handler)
3928 // This is the constructor signature for "ordinary" (non-vertex)
3929 // accessors and we shouldn't be calling it altogether. But it is also
3930 // the constructor that the default-constructor of TriaRawIterator
3931 // calls when default-constructing an iterator object. If so, this
3932 // happens with level==-2 and index==-2, and this is the only case we
3933 // would like to support. We do this by just forwarding to the
3934 // other constructor of this class, and then asserting the condition
3935 // on level and index.
3936 : DoFAccessor<0, 1, spacedim, level_dof_access>(
3937 tria,
3938 TriaAccessor<0, 1, spacedim>::interior_vertex,
3939 0U,
3940 dof_handler)
3941 {
3942 (void)level;
3943 (void)index;
3944 Assert((tria == nullptr) && (level == -2) && (index == -2) &&
3945 (dof_handler == nullptr),
3946 ExcMessage(
3947 "This constructor can not be called for face iterators in 1d, "
3948 "except to default-construct iterator objects."));
3949 }
3950
3951
3952
3953 template <int spacedim, bool level_dof_access>
3954 template <int structdim2, int dim2, int spacedim2>
3955 DoFAccessor<0, 1, spacedim, level_dof_access>::DoFAccessor(
3956 const InvalidAccessor<structdim2, dim2, spacedim2> &)
3957 {
3958 Assert(false, ExcInvalidObject());
3959 }
3960
3961
3962
3963 template <int spacedim, bool level_dof_access>
3964 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
3965 inline DoFAccessor<0, 1, spacedim, level_dof_access>::DoFAccessor(
3966 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &)
3967 {
3968 Assert(false, ExcInvalidObject());
3969 }
3970
3971
3972
3973 template <int spacedim, bool level_dof_access>
3974 inline void
3975 DoFAccessor<0, 1, spacedim, level_dof_access>::set_dof_handler(
3976 DoFHandler<1, spacedim> *dh)
3977 {
3978 Assert(dh != nullptr, ExcInvalidObject());
3979 this->dof_handler = dh;
3980 }
3981
3982
3983
3984 template <int spacedim, bool level_dof_access>
3985 inline void
3986 DoFAccessor<0, 1, spacedim, level_dof_access>::set_dof_index(
3987 const unsigned int /*i*/,
3988 const types::global_dof_index /*index*/,
3989 const types::fe_index /*fe_index*/) const
3990 {
3991 DEAL_II_NOT_IMPLEMENTED();
3992 }
3993
3994
3995
3996 template <int spacedim, bool level_dof_access>
3997 inline const DoFHandler<1, spacedim> &
3998 DoFAccessor<0, 1, spacedim, level_dof_access>::get_dof_handler() const
3999 {
4000 return *this->dof_handler;
4001 }
4002
4003
4004
4005 template <int spacedim, bool level_dof_access>
4006 inline void
4007 DoFAccessor<0, 1, spacedim, level_dof_access>::get_dof_indices(
4008 std::vector<types::global_dof_index> &dof_indices,
4009 const types::fe_index fe_index_) const
4010 {
4011 const auto fe_index =
4012 internal::DoFAccessorImplementation::get_fe_index_or_default(*this,
4013 fe_index_);
4014
4015 for (unsigned int i = 0; i < dof_indices.size(); ++i)
4016 dof_indices[i] = dealii::internal::DoFAccessorImplementation::
4017 Implementation::get_dof_index(*dof_handler,
4018 0,
4019 this->global_vertex_index,
4020 fe_index,
4021 i,
4022 std::integral_constant<int, 0>());
4023 }
4024
4025
4026
4027 template <int spacedim, bool level_dof_access>
4028 inline void
4029 DoFAccessor<0, 1, spacedim, level_dof_access>::get_mg_dof_indices(
4030 const int level,
4031 std::vector<types::global_dof_index> &dof_indices,
4032 const types::fe_index fe_index_) const
4033 {
4034 const auto fe_index =
4035 internal::DoFAccessorImplementation::get_fe_index_or_default(*this,
4036 fe_index_);
4037 (void)fe_index;
4038 AssertDimension(fe_index, (DoFHandler<1, spacedim>::default_fe_index));
4039
4040 for (unsigned int i = 0; i < dof_indices.size(); ++i)
4041 dof_indices[i] =
4042 dealii::internal::DoFAccessorImplementation::Implementation::
4043 mg_vertex_dof_index(*dof_handler, level, this->global_vertex_index, i);
4044 }
4045
4046
4047
4048 template <int spacedim, bool level_dof_access>
4049 inline types::global_dof_index
4050 DoFAccessor<0, 1, spacedim, level_dof_access>::vertex_dof_index(
4051 const unsigned int vertex,
4052 const unsigned int i,
4053 const types::fe_index fe_index_) const
4054 {
4055 const auto fe_index =
4056 internal::DoFAccessorImplementation::get_fe_index_or_default(*this,
4057 fe_index_);
4058
4059 (void)vertex;
4060 AssertIndexRange(vertex, 1);
4061 return dealii::internal::DoFAccessorImplementation::Implementation::
4062 get_dof_index(*dof_handler,
4063 0,
4064 this->global_vertex_index,
4065 fe_index,
4066 i,
4067 std::integral_constant<int, 0>());
4068 }
4069
4070
4071
4072 template <int spacedim, bool level_dof_access>
4073 inline types::global_dof_index
4074 DoFAccessor<0, 1, spacedim, level_dof_access>::dof_index(
4075 const unsigned int i,
4076 const types::fe_index fe_index_) const
4077 {
4078 const auto fe_index =
4079 internal::DoFAccessorImplementation::get_fe_index_or_default(*this,
4080 fe_index_);
4081
4082 return dealii::internal::DoFAccessorImplementation::Implementation::
4083 get_dof_index(*this->dof_handler,
4084 0,
4085 this->vertex_index(0),
4086 fe_index,
4087 i,
4088 std::integral_constant<int, 0>());
4089 }
4090
4091
4092
4093 template <int spacedim, bool level_dof_access>
4094 inline unsigned int
4095 DoFAccessor<0, 1, spacedim, level_dof_access>::n_active_fe_indices() const
4096 {
4097 return 1;
4098 }
4099
4100
4101
4102 template <int spacedim, bool level_dof_access>
4103 inline types::fe_index
4104 DoFAccessor<0, 1, spacedim, level_dof_access>::nth_active_fe_index(
4105 const unsigned int /*n*/) const
4106 {
4107 return 0;
4108 }
4109
4110
4111
4112 template <int spacedim, bool level_dof_access>
4113 inline bool
4114 DoFAccessor<0, 1, spacedim, level_dof_access>::fe_index_is_active(
4115 const types::fe_index /*fe_index*/) const
4116 {
4117 DEAL_II_NOT_IMPLEMENTED();
4118 return false;
4119 }
4120
4121
4122
4123 template <int spacedim, bool level_dof_access>
4124 inline const FiniteElement<1, spacedim> &
4125 DoFAccessor<0, 1, spacedim, level_dof_access>::get_fe(
4126 const types::fe_index fe_index) const
4127 {
4128 Assert(this->dof_handler != nullptr, ExcInvalidObject());
4129 return dof_handler->get_fe(fe_index);
4130 }
4131
4132
4133
4134 template <int spacedim, bool level_dof_access>
4135 inline void
4136 DoFAccessor<0, 1, spacedim, level_dof_access>::copy_from(
4137 const TriaAccessorBase<0, 1, spacedim> &da)
4138 {
4139 Assert(this->dof_handler != nullptr, ExcInvalidObject());
4140 BaseClass::copy_from(da);
4141 }
4142
4143
4144
4145 template <int spacedim, bool level_dof_access>
4146 template <bool level_dof_access2>
4147 inline void
4148 DoFAccessor<0, 1, spacedim, level_dof_access>::copy_from(
4149 const DoFAccessor<0, 1, spacedim, level_dof_access2> &a)
4150 {
4151 BaseClass::copy_from(a);
4152 set_dof_handler(a.dof_handler);
4153 }
4154
4155
4156
4157 template <int spacedim, bool level_dof_access>
4158 inline TriaIterator<DoFAccessor<0, 1, spacedim, level_dof_access>>
4159 DoFAccessor<0, 1, spacedim, level_dof_access>::child(
4160 const unsigned int /*i*/) const
4161 {
4162 return TriaIterator<DoFAccessor<0, 1, spacedim, level_dof_access>>();
4163 }
4164
4165
4166
4167 template <int spacedim, bool level_dof_access>
4168 inline typename dealii::internal::DoFHandlerImplementation::
4169 Iterators<1, spacedim, level_dof_access>::line_iterator
4170 DoFAccessor<0, 1, spacedim, level_dof_access>::line(
4171 const unsigned int /*c*/) const
4172 {
4173 DEAL_II_NOT_IMPLEMENTED();
4174 return typename dealii::internal::DoFHandlerImplementation::
4175 Iterators<1, spacedim, level_dof_access>::line_iterator();
4176 }
4177
4178
4179
4180 template <int spacedim, bool level_dof_access>
4181 inline typename dealii::internal::DoFHandlerImplementation::
4182 Iterators<1, spacedim, level_dof_access>::quad_iterator
4183 DoFAccessor<0, 1, spacedim, level_dof_access>::quad(
4184 const unsigned int /*c*/) const
4185 {
4186 DEAL_II_NOT_IMPLEMENTED();
4187 return typename dealii::internal::DoFHandlerImplementation::
4188 Iterators<1, spacedim, level_dof_access>::quad_iterator();
4189 }
4190
4191
4192
4193 template <int spacedim, bool level_dof_access>
4194 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
4195 inline bool
4196 DoFAccessor<0, 1, spacedim, level_dof_access>::operator==(
4197 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &a) const
4198 {
4199 Assert(structdim2 == 0, ExcCantCompareIterators());
4200 Assert(this->dof_handler == a.dof_handler, ExcCantCompareIterators());
4201 return (BaseClass::operator==(a));
4202 }
4203
4204
4205
4206 template <int spacedim, bool level_dof_access>
4207 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
4208 inline bool
4209 DoFAccessor<0, 1, spacedim, level_dof_access>::operator!=(
4210 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &a) const
4211 {
4212 Assert(structdim2 == 0, ExcCantCompareIterators());
4213 Assert(this->dof_handler == a.dof_handler, ExcCantCompareIterators());
4214 return (BaseClass::operator!=(a));
4215 }
4216
4217
4218
4219 /*------------------------- Functions: DoFCellAccessor -----------------------*/
4220
4221
4222 namespace internal
4223 {
4224 namespace DoFCellAccessorImplementation
4225 {
4226 /**
4227 * A class with the same purpose as the similarly named class of the
4228 * Triangulation class. See there for more information.
4229 */
4230 struct Implementation
4231 {
4232 /**
4233 * Do what the active_fe_index function in the parent class is supposed to
4234 * do.
4235 */
4236 template <int dim, int spacedim, bool level_dof_access>
4237 static types::fe_index
4238 active_fe_index(
4239 const DoFCellAccessor<dim, spacedim, level_dof_access> &accessor)
4240 {
4241 if (accessor.dof_handler->hp_capability_enabled == false)
4242 return DoFHandler<dim, spacedim>::default_fe_index;
4243
4244 Assert(accessor.dof_handler != nullptr,
4245 (typename std::decay_t<decltype(accessor)>::ExcInvalidObject()));
4246 Assert(static_cast<unsigned int>(accessor.level()) <
4247 accessor.dof_handler->hp_cell_future_fe_indices.size(),
4248 ExcMessage("DoFHandler not initialized"));
4249
4250 return accessor.dof_handler
4251 ->hp_cell_active_fe_indices[accessor.level()][accessor.present_index];
4252 }
4253
4254
4255
4256 /**
4257 * Do what the set_active_fe_index function in the parent class is
4258 * supposed to do.
4259 */
4260 template <int dim, int spacedim, bool level_dof_access>
4261 static void
4262 set_active_fe_index(
4263 const DoFCellAccessor<dim, spacedim, level_dof_access> &accessor,
4264 const types::fe_index i)
4265 {
4266 if (accessor.dof_handler->hp_capability_enabled == false)
4267 {
4268 AssertDimension(i, (DoFHandler<dim, spacedim>::default_fe_index));
4269 return;
4270 }
4271
4272 Assert(accessor.dof_handler != nullptr,
4273 (typename std::decay_t<decltype(accessor)>::ExcInvalidObject()));
4274 Assert(static_cast<unsigned int>(accessor.level()) <
4275 accessor.dof_handler->hp_cell_future_fe_indices.size(),
4276 ExcMessage("DoFHandler not initialized"));
4277 Assert(i != numbers::invalid_fe_index,
4278 ExcMessage("Invalid finite element index."));
4279
4280 accessor.dof_handler
4281 ->hp_cell_active_fe_indices[accessor.level()]
4282 [accessor.present_index] = i;
4283 }
4284
4285
4286
4287 /**
4288 * Do what the future_fe_index function in the parent class is supposed to
4289 * do.
4290 */
4291 template <int dim, int spacedim, bool level_dof_access>
4292 static types::fe_index
4293 future_fe_index(
4294 const DoFCellAccessor<dim, spacedim, level_dof_access> &accessor)
4295 {
4296 if (accessor.dof_handler->hp_capability_enabled == false)
4297 return DoFHandler<dim, spacedim>::default_fe_index;
4298
4299 Assert(accessor.dof_handler != nullptr,
4300 (typename std::decay_t<decltype(accessor)>::ExcInvalidObject()));
4301 Assert(static_cast<unsigned int>(accessor.level()) <
4302 accessor.dof_handler->hp_cell_future_fe_indices.size(),
4303 ExcMessage("DoFHandler not initialized"));
4304
4305 if (future_fe_index_set(accessor))
4306 return accessor.dof_handler
4307 ->hp_cell_future_fe_indices[accessor.level()]
4308 [accessor.present_index];
4309 else
4310 return accessor.dof_handler
4311 ->hp_cell_active_fe_indices[accessor.level()]
4312 [accessor.present_index];
4313 }
4314
4315
4316 /**
4317 * Do what the set_future_fe_index function in the parent class is
4318 * supposed to do.
4319 */
4320 template <int dim, int spacedim, bool level_dof_access>
4321 static void
4322 set_future_fe_index(
4323 const DoFCellAccessor<dim, spacedim, level_dof_access> &accessor,
4324 const types::fe_index i)
4325 {
4326 if (accessor.dof_handler->hp_capability_enabled == false)
4327 {
4328 AssertDimension(i, (DoFHandler<dim, spacedim>::default_fe_index));
4329 return;
4330 }
4331
4332 Assert(accessor.dof_handler != nullptr,
4333 (typename std::decay_t<decltype(accessor)>::ExcInvalidObject()));
4334 Assert(static_cast<unsigned int>(accessor.level()) <
4335 accessor.dof_handler->hp_cell_future_fe_indices.size(),
4336 ExcMessage("DoFHandler not initialized"));
4337 Assert(i != numbers::invalid_fe_index,
4338 ExcMessage("Invalid finite element index."));
4339
4340 accessor.dof_handler
4341 ->hp_cell_future_fe_indices[accessor.level()]
4342 [accessor.present_index] = i;
4343 }
4344
4345
4346
4347 /**
4348 * Do what the future_fe_index_set function in the parent class is
4349 * supposed to do.
4350 */
4351 template <int dim, int spacedim, bool level_dof_access>
4352 static bool
4353 future_fe_index_set(
4354 const DoFCellAccessor<dim, spacedim, level_dof_access> &accessor)
4355 {
4356 if (accessor.dof_handler->hp_capability_enabled == false)
4357 return false;
4358
4359 Assert(accessor.dof_handler != nullptr,
4360 (typename std::decay_t<decltype(accessor)>::ExcInvalidObject()));
4361 Assert(static_cast<unsigned int>(accessor.level()) <
4362 accessor.dof_handler->hp_cell_future_fe_indices.size(),
4363 ExcMessage("DoFHandler not initialized"));
4364
4365 return accessor.dof_handler
4366 ->hp_cell_future_fe_indices[accessor.level()]
4367 [accessor.present_index] !=
4368 numbers::invalid_fe_index;
4369 }
4370
4371
4372
4373 /**
4374 * Do what the clear_fe_index function in the parent class is supposed to
4375 * do.
4376 */
4377 template <int dim, int spacedim, bool level_dof_access>
4378 static void
4379 clear_future_fe_index(
4380 const DoFCellAccessor<dim, spacedim, level_dof_access> &accessor)
4381 {
4382 if (accessor.dof_handler->hp_capability_enabled == false)
4383 return;
4384
4385 Assert(accessor.dof_handler != nullptr,
4386 (typename std::decay_t<decltype(accessor)>::ExcInvalidObject()));
4387 Assert(static_cast<unsigned int>(accessor.level()) <
4388 accessor.dof_handler->hp_cell_future_fe_indices.size(),
4389 ExcMessage("DoFHandler not initialized"));
4390
4391 accessor.dof_handler
4392 ->hp_cell_future_fe_indices[accessor.level()]
4393 [accessor.present_index] =
4394 numbers::invalid_fe_index;
4395 }
4396 };
4397 } // namespace DoFCellAccessorImplementation
4398 } // namespace internal
4399
4400
4401
4402 template <int dimension_, int space_dimension_, bool level_dof_access>
4403 inline DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4404 DoFCellAccessor(const Triangulation<dimension_, space_dimension_> *tria,
4405 const int level,
4406 const int index,
4407 const AccessorData *local_data)
4408 : DoFAccessor<dimension_, dimension_, space_dimension_, level_dof_access>(
4409 tria,
4410 level,
4411 index,
4412 local_data)
4413 {}
4414
4415
4416
4417 template <int dimension_, int space_dimension_, bool level_dof_access>
4418 template <int structdim2, int dim2, int spacedim2>
4419 inline DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4420 DoFCellAccessor(const InvalidAccessor<structdim2, dim2, spacedim2> &)
4421 {
4422 Assert(false, typename BaseClass::ExcInvalidObject());
4423 }
4424
4425
4426
4427 template <int dimension_, int space_dimension_, bool level_dof_access>
4428 template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
4429 inline DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4430 DoFCellAccessor(
4431 const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &other)
4432 : BaseClass(other)
4433 {}
4434
4435
4436
4437 template <int dimension_, int space_dimension_, bool level_dof_access>
4438 inline TriaIterator<
4439 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
4440 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::neighbor(
4441 const unsigned int i) const
4442 {
4443 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
4444 q(this->tria,
4445 this->neighbor_level(i),
4446 this->neighbor_index(i),
4447 this->dof_handler);
4448
4449 if constexpr (running_in_debug_mode())
4450 {
4451 if (q.state() != IteratorState::past_the_end)
4452 Assert(q->used(), ExcInternalError());
4453 }
4454 return q;
4455 }
4456
4457
4458
4459 template <int dimension_, int space_dimension_, bool level_dof_access>
4460 inline TriaIterator<
4461 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
4462 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::child(
4463 const unsigned int i) const
4464 {
4465 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
4466 q(this->tria, this->level() + 1, this->child_index(i), this->dof_handler);
4467
4468 if constexpr (running_in_debug_mode())
4469 {
4470 if (q.state() != IteratorState::past_the_end)
4471 Assert(q->used(), ExcInternalError());
4472 }
4473 return q;
4474 }
4475
4476
4477
4478 template <int dimension_, int space_dimension_, bool level_dof_access>
4479 inline boost::container::small_vector<
4480 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>,
4481 GeometryInfo<dimension_>::max_children_per_cell>
4482 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4483 child_iterators() const
4484 {
4485 boost::container::small_vector<
4486 TriaIterator<
4487 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>,
4488 GeometryInfo<dimension_>::max_children_per_cell>
4489 child_iterators(this->n_children());
4490
4491 for (unsigned int i = 0; i < this->n_children(); ++i)
4492 child_iterators[i] = this->child(i);
4493
4494 return child_iterators;
4495 }
4496
4497
4498
4499 template <int dimension_, int space_dimension_, bool level_dof_access>
4500 inline TriaIterator<
4501 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
4502 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::parent() const
4503 {
4504 TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
4505 q(this->tria, this->level() - 1, this->parent_index(), this->dof_handler);
4506
4507 return q;
4508 }
4509
4510
4511
4512 namespace internal
4513 {
4514 namespace DoFCellAccessorImplementation
4515 {
4516 template <int dim, int spacedim, bool level_dof_access>
4517 inline TriaIterator<
4518 dealii::DoFAccessor<dim - 1, dim, spacedim, level_dof_access>>
4519 get_face(
4520 const dealii::DoFCellAccessor<dim, spacedim, level_dof_access> &cell,
4521 const unsigned int i,
4522 const std::integral_constant<int, 1>)
4523 {
4524 dealii::DoFAccessor<0, dim, spacedim, level_dof_access> a(
4525 &cell.get_triangulation(),
4526 ((i == 0) && cell.at_boundary(0) ?
4527 dealii::TriaAccessor<0, 1, spacedim>::left_vertex :
4528 ((i == 1) && cell.at_boundary(1) ?
4529 dealii::TriaAccessor<0, 1, spacedim>::right_vertex :
4530 dealii::TriaAccessor<0, 1, spacedim>::interior_vertex)),
4531 cell.vertex_index(i),
4532 &cell.get_dof_handler());
4533 return dealii::TriaIterator<
4534 dealii::DoFAccessor<0, dim, spacedim, level_dof_access>>(a);
4535 }
4536
4537
4538 template <int dim, int spacedim, bool level_dof_access>
4539 inline TriaIterator<
4540 dealii::DoFAccessor<dim - 1, dim, spacedim, level_dof_access>>
4541 get_face(
4542 const dealii::DoFCellAccessor<dim, spacedim, level_dof_access> &cell,
4543 const unsigned int i,
4544 const std::integral_constant<int, 2>)
4545 {
4546 return cell.line(i);
4547 }
4548
4549
4550 template <int dim, int spacedim, bool level_dof_access>
4551 inline TriaIterator<
4552 dealii::DoFAccessor<dim - 1, dim, spacedim, level_dof_access>>
4553 get_face(
4554 const dealii::DoFCellAccessor<dim, spacedim, level_dof_access> &cell,
4555 const unsigned int i,
4556 const std::integral_constant<int, 3>)
4557 {
4558 return cell.quad(i);
4559 }
4560 } // namespace DoFCellAccessorImplementation
4561 } // namespace internal
4562
4563
4564
4565 template <int dimension_, int space_dimension_, bool level_dof_access>
4566 inline typename DoFCellAccessor<dimension_,
4567 space_dimension_,
4568 level_dof_access>::face_iterator
4569 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::face(
4570 const unsigned int i) const
4571 {
4572 AssertIndexRange(i, this->n_faces());
4573
4574 return dealii::internal::DoFCellAccessorImplementation::get_face(
4575 *this, i, std::integral_constant<int, dimension_>());
4576 }
4577
4578
4579
4580 template <int dimension_, int space_dimension_, bool level_dof_access>
4581 inline boost::container::small_vector<
4582 typename DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4583 face_iterator,
4584 GeometryInfo<dimension_>::faces_per_cell>
4585 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4586 face_iterators() const
4587 {
4588 boost::container::small_vector<
4589 typename DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4590 face_iterator,
4591 GeometryInfo<dimension_>::faces_per_cell>
4592 face_iterators(this->n_faces());
4593
4594 for (const unsigned int i : this->face_indices())
4595 face_iterators[i] =
4596 dealii::internal::DoFCellAccessorImplementation::get_face(
4597 *this, i, std::integral_constant<int, dimension_>());
4598
4599 return face_iterators;
4600 }
4601
4602
4603
4604 template <int dimension_, int space_dimension_, bool level_dof_access>
4605 inline void
4606 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4607 get_active_or_mg_dof_indices(
4608 std::vector<types::global_dof_index> &dof_indices) const
4609 {
4610 if (level_dof_access)
4611 get_mg_dof_indices(dof_indices);
4612 else
4613 get_dof_indices(dof_indices);
4614 }
4615
4616
4617
4618 template <int dimension_, int space_dimension_, bool level_dof_access>
4619 template <class InputVector, typename number>
4620 inline void
4621 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::get_dof_values(
4622 const InputVector &values,
4623 Vector<number> &local_values) const
4624 {
4625 get_dof_values(values, local_values.begin(), local_values.end());
4626 }
4627
4628
4629
4630 template <int dimension_, int space_dimension_, bool level_dof_access>
4631 template <typename Number, typename ForwardIterator>
4632 inline void
4633 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::get_dof_values(
4634 const ReadVector<Number> &values,
4635 ForwardIterator local_values_begin,
4636 ForwardIterator local_values_end) const
4637 {
4638 (void)local_values_end;
4639 Assert(this->is_artificial() == false,
4640 ExcMessage("Can't ask for DoF indices on artificial cells."));
4641 Assert(this->is_active(), ExcMessage("Cell must be active."));
4642 Assert(this->dof_handler != nullptr, typename BaseClass::ExcInvalidObject());
4643
4644 Assert(static_cast<unsigned int>(local_values_end - local_values_begin) ==
4645 this->get_fe().n_dofs_per_cell(),
4646 typename DoFCellAccessor::ExcVectorDoesNotMatch());
4647 Assert(values.size() == this->get_dof_handler().n_dofs(),
4648 typename DoFCellAccessor::ExcVectorDoesNotMatch());
4649
4650 internal::DoFAccessorImplementation::Implementation::dof_index_vector_type
4651 dof_indices(this->get_fe().n_dofs_per_cell());
4652 internal::DoFAccessorImplementation::get_cell_dof_indices(
4653 *this, dof_indices, this->active_fe_index());
4654
4655 boost::container::small_vector<Number, 27> values_temp(local_values_end -
4656 local_values_begin);
4657 auto view = make_array_view(values_temp.begin(), values_temp.end());
4658 values.extract_subvector_to(make_array_view(dof_indices.begin(),
4659 dof_indices.end()),
4660 view);
4661 using view_type = std::remove_reference_t<decltype(*local_values_begin)>;
4662 ArrayView<view_type> values_view2(&*local_values_begin,
4663 local_values_end - local_values_begin);
4664 std::copy(values_temp.begin(), values_temp.end(), values_view2.begin());
4665 }
4666
4667
4668
4669 template <int dimension_, int space_dimension_, bool level_dof_access>
4670 template <class InputVector, typename ForwardIterator>
4671 inline void
4672 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::get_dof_values(
4673 const AffineConstraints<typename InputVector::value_type> &constraints,
4674 const InputVector &values,
4675 ForwardIterator local_values_begin,
4676 ForwardIterator local_values_end) const
4677 {
4678 Assert(this->is_artificial() == false,
4679 ExcMessage("Can't ask for DoF indices on artificial cells."));
4680 Assert(this->is_active(), ExcMessage("Cell must be active."));
4681
4682 Assert(static_cast<unsigned int>(local_values_end - local_values_begin) ==
4683 this->get_fe().n_dofs_per_cell(),
4684 typename DoFCellAccessor::ExcVectorDoesNotMatch());
4685 Assert(values.size() == this->get_dof_handler().n_dofs(),
4686 typename DoFCellAccessor::ExcVectorDoesNotMatch());
4687
4688
4689 internal::DoFAccessorImplementation::Implementation::dof_index_vector_type
4690 dof_indices(this->get_fe().n_dofs_per_cell());
4691 internal::DoFAccessorImplementation::get_cell_dof_indices(
4692 *this, dof_indices, this->active_fe_index());
4693
4694 constraints.get_dof_values(values,
4695 dof_indices.data(),
4696 local_values_begin,
4697 local_values_end);
4698 }
4699
4700
4701
4702 template <int dimension_, int space_dimension_, bool level_dof_access>
4703 template <class OutputVector, typename number>
4704 inline void
4705 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::set_dof_values(
4706 const Vector<number> &local_values,
4707 OutputVector &values) const
4708 {
4709 Assert(this->is_artificial() == false,
4710 ExcMessage("Can't ask for DoF indices on artificial cells."));
4711 Assert(this->is_active(), ExcMessage("Cell must be active."));
4712
4713 Assert(static_cast<unsigned int>(local_values.size()) ==
4714 this->get_fe().n_dofs_per_cell(),
4715 typename DoFCellAccessor::ExcVectorDoesNotMatch());
4716 Assert(values.size() == this->get_dof_handler().n_dofs(),
4717 typename DoFCellAccessor::ExcVectorDoesNotMatch());
4718
4719
4720 Assert(this->dof_handler != nullptr, typename BaseClass::ExcInvalidObject());
4721 internal::DoFAccessorImplementation::Implementation::dof_index_vector_type
4722 dof_indices(this->get_fe().n_dofs_per_cell());
4723 internal::DoFAccessorImplementation::get_cell_dof_indices(
4724 *this, dof_indices, this->active_fe_index());
4725
4726 for (unsigned int i = 0; i < this->get_fe().n_dofs_per_cell(); ++i)
4727 internal::ElementAccess<OutputVector>::set(local_values(i),
4728 dof_indices[i],
4729 values);
4730 }
4731
4732
4733
4734 template <int dimension_, int space_dimension_, bool level_dof_access>
4735 inline const FiniteElement<dimension_, space_dimension_> &
4736 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::get_fe() const
4737 {
4738 Assert(this->dof_handler != nullptr, typename BaseClass::ExcInvalidObject());
4739 Assert((this->dof_handler->hp_capability_enabled == false) ||
4740 this->is_active(),
4741 ExcMessage(
4742 "For DoFHandler objects in hp-mode, finite elements are only "
4743 "associated with active cells. Consequently, you can not ask "
4744 "for the active finite element on cells with children."));
4745
4746 const auto &fe = this->dof_handler->get_fe(active_fe_index());
4747
4748 Assert(this->reference_cell() == fe.reference_cell(),
4749 internal::ExcNonMatchingReferenceCellTypes(this->reference_cell(),
4750 fe.reference_cell()));
4751
4752 return fe;
4753 }
4754
4755
4756
4757 template <int dimension_, int space_dimension_, bool level_dof_access>
4758 inline types::fe_index
4759 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4760 active_fe_index() const
4761 {
4762 Assert((this->dof_handler->hp_capability_enabled == false) ||
4763 this->is_active(),
4764 ExcMessage(
4765 "You can not ask for the active FE index on a cell that has "
4766 "children because no degrees of freedom are assigned "
4767 "to this cell and, consequently, no finite element "
4768 "is associated with it."));
4769 Assert((this->dof_handler->hp_capability_enabled == false) ||
4770 (this->is_locally_owned() || this->is_ghost()),
4771 ExcMessage("You can only query active FE index information on cells "
4772 "that are either locally owned or (after distributing "
4773 "degrees of freedom) are ghost cells."));
4774
4775 return dealii::internal::DoFCellAccessorImplementation::Implementation::
4776 active_fe_index(*this);
4777 }
4778
4779
4780
4781 template <int dimension_, int space_dimension_, bool level_dof_access>
4782 inline void
4783 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4784 set_active_fe_index(const types::fe_index i) const
4785 {
4786 Assert((this->dof_handler->hp_capability_enabled == false) ||
4787 this->is_active(),
4788 ExcMessage("You can not set the active FE index on a cell that has "
4789 "children because no degrees of freedom will be assigned "
4790 "to this cell."));
4791
4792 Assert((this->dof_handler->hp_capability_enabled == false) ||
4793 this->is_locally_owned(),
4794 ExcMessage("You can only set active FE index information on cells "
4795 "that are locally owned. On ghost cells, this information "
4796 "will automatically be propagated from the owning process "
4797 "of that cell, and there is no information at all on "
4798 "artificial cells."));
4799
4800 dealii::internal::DoFCellAccessorImplementation::Implementation::
4801 set_active_fe_index(*this, i);
4802 }
4803
4804
4805
4806 template <int dimension_, int space_dimension_, bool level_dof_access>
4807 inline const FiniteElement<dimension_, space_dimension_> &
4808 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::get_future_fe()
4809 const
4810 {
4811 Assert(this->dof_handler != nullptr, typename BaseClass::ExcInvalidObject());
4812 Assert((this->dof_handler->hp_capability_enabled == false) ||
4813 this->is_active(),
4814 ExcMessage(
4815 "For DoFHandler objects in hp-mode, finite elements are only "
4816 "associated with active cells. Consequently, you can not ask "
4817 "for the future finite element on cells with children."));
4818
4819 return this->dof_handler->get_fe(future_fe_index());
4820 }
4821
4822
4823
4824 template <int dimension_, int space_dimension_, bool level_dof_access>
4825 inline types::fe_index
4826 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4827 future_fe_index() const
4828 {
4829 Assert((this->dof_handler->hp_capability_enabled == false) ||
4830 (this->has_children() == false),
4831 ExcMessage(
4832 "You can not ask for the future FE index on a cell that has "
4833 "children because no degrees of freedom are assigned "
4834 "to this cell and, consequently, no finite element "
4835 "is associated with it."));
4836 Assert((this->dof_handler->hp_capability_enabled == false) ||
4837 (this->is_locally_owned()),
4838 ExcMessage("You can only query future FE index information on cells "
4839 "that are locally owned."));
4840
4841 return dealii::internal::DoFCellAccessorImplementation::Implementation::
4842 future_fe_index(*this);
4843 }
4844
4845
4846
4847 template <int dimension_, int space_dimension_, bool level_dof_access>
4848 inline void
4849 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4850 set_future_fe_index(const types::fe_index i) const
4851 {
4852 Assert((this->dof_handler->hp_capability_enabled == false) ||
4853 (this->has_children() == false),
4854 ExcMessage("You can not set the future FE index on a cell that has "
4855 "children because no degrees of freedom will be assigned "
4856 "to this cell."));
4857
4858 Assert((this->dof_handler->hp_capability_enabled == false) ||
4859 this->is_locally_owned(),
4860 ExcMessage("You can only set future FE index information on cells "
4861 "that are locally owned."));
4862
4863 dealii::internal::DoFCellAccessorImplementation::Implementation::
4864 set_future_fe_index(*this, i);
4865 }
4866
4867
4868
4869 template <int dimension_, int space_dimension_, bool level_dof_access>
4870 inline bool
4871 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4872 future_fe_index_set() const
4873 {
4874 Assert((this->dof_handler->hp_capability_enabled == false) ||
4875 (this->has_children() == false),
4876 ExcMessage(
4877 "You can not ask for the future FE index on a cell that has "
4878 "children because no degrees of freedom are assigned "
4879 "to this cell and, consequently, no finite element "
4880 "is associated with it."));
4881 Assert((this->dof_handler->hp_capability_enabled == false) ||
4882 (this->is_locally_owned()),
4883 ExcMessage("You can only query future FE index information on cells "
4884 "that are locally owned."));
4885
4886 return dealii::internal::DoFCellAccessorImplementation::Implementation::
4887 future_fe_index_set(*this);
4888 }
4889
4890
4891
4892 template <int dimension_, int space_dimension_, bool level_dof_access>
4893 inline void
4894 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4895 clear_future_fe_index() const
4896 {
4897 Assert((this->dof_handler->hp_capability_enabled == false) ||
4898 (this->has_children() == false),
4899 ExcMessage(
4900 "You can not ask for the future FE index on a cell that has "
4901 "children because no degrees of freedom are assigned "
4902 "to this cell and, consequently, no finite element "
4903 "is associated with it."));
4904 Assert((this->dof_handler->hp_capability_enabled == false) ||
4905 (this->is_locally_owned()),
4906 ExcMessage("You can only query future FE index information on cells "
4907 "that are locally owned."));
4908
4909 dealii::internal::DoFCellAccessorImplementation::Implementation::
4910 clear_future_fe_index(*this);
4911 }
4912
4913
4914
4915 template <int dimension_, int space_dimension_, bool level_dof_access>
4916 template <typename number, typename OutputVector>
4917 inline void
4918 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4919 distribute_local_to_global(const Vector<number> &local_source,
4920 OutputVector &global_destination) const
4921 {
4922 this->distribute_local_to_global(local_source.begin(),
4923 local_source.end(),
4924 global_destination);
4925 }
4926
4927
4928
4929 template <int dimension_, int space_dimension_, bool level_dof_access>
4930 template <typename ForwardIterator, typename OutputVector>
4931 inline void
4932 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4933 distribute_local_to_global(ForwardIterator local_source_begin,
4934 ForwardIterator local_source_end,
4935 OutputVector &global_destination) const
4936 {
4937 Assert(this->dof_handler != nullptr,
4938 (typename std::decay_t<decltype(*this)>::ExcInvalidObject()));
4939 Assert(static_cast<unsigned int>(local_source_end - local_source_begin) ==
4940 this->get_fe().n_dofs_per_cell(),
4941 (typename std::decay_t<decltype(*this)>::ExcVectorDoesNotMatch()));
4942 Assert(this->dof_handler->n_dofs() == global_destination.size(),
4943 (typename std::decay_t<decltype(*this)>::ExcVectorDoesNotMatch()));
4944
4945 Assert(!this->has_children(), ExcMessage("Cell must be active"));
4946
4947 Assert(
4948 internal::ArrayViewHelper::is_contiguous(local_source_begin,
4949 local_source_end),
4950 ExcMessage(
4951 "This function can not be called with iterator types that do not point to contiguous memory."));
4952
4953 const unsigned int n_dofs = local_source_end - local_source_begin;
4954
4955 internal::DoFAccessorImplementation::Implementation::dof_index_vector_type
4956 dof_indices(n_dofs);
4957 internal::DoFAccessorImplementation::get_cell_dof_indices(
4958 *this, dof_indices, this->active_fe_index());
4959
4960 // distribute cell vector
4961 global_destination.add(n_dofs, dof_indices.data(), &(*local_source_begin));
4962 }
4963
4964
4965
4966 template <int dimension_, int space_dimension_, bool level_dof_access>
4967 template <typename ForwardIterator, typename OutputVector>
4968 inline void
4969 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
4970 distribute_local_to_global(
4971 const AffineConstraints<typename OutputVector::value_type> &constraints,
4972 ForwardIterator local_source_begin,
4973 ForwardIterator local_source_end,
4974 OutputVector &global_destination) const
4975 {
4976 Assert(this->dof_handler != nullptr,
4977 (typename std::decay_t<decltype(*this)>::ExcInvalidObject()));
4978 Assert(local_source_end - local_source_begin ==
4979 this->get_fe().n_dofs_per_cell(),
4980 (typename std::decay_t<decltype(*this)>::ExcVectorDoesNotMatch()));
4981 Assert(this->dof_handler->n_dofs() == global_destination.size(),
4982 (typename std::decay_t<decltype(*this)>::ExcVectorDoesNotMatch()));
4983
4984 Assert(!this->has_children(), ExcMessage("Cell must be active."));
4985
4986 internal::DoFAccessorImplementation::Implementation::dof_index_vector_type
4987 dof_indices(this->get_fe().n_dofs_per_cell());
4988 internal::DoFAccessorImplementation::get_cell_dof_indices(
4989 *this, dof_indices, this->active_fe_index());
4990
4991 // distribute cell vector
4992 constraints.distribute_local_to_global(local_source_begin,
4993 local_source_end,
4994 dof_indices.data(),
4995 global_destination);
4996 }
4997
4998
4999
5000 template <int dimension_, int space_dimension_, bool level_dof_access>
5001 template <typename number, typename OutputMatrix>
5002 inline void
5003 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
5004 distribute_local_to_global(const FullMatrix<number> &local_source,
5005 OutputMatrix &global_destination) const
5006 {
5007 Assert(this->dof_handler != nullptr,
5008 (typename std::decay_t<decltype(*this)>::ExcInvalidObject()));
5009 Assert(local_source.m() == this->get_fe().n_dofs_per_cell(),
5010 (typename std::decay_t<decltype(*this)>::ExcMatrixDoesNotMatch()));
5011 Assert(local_source.n() == this->get_fe().n_dofs_per_cell(),
5012 (typename std::decay_t<decltype(*this)>::ExcMatrixDoesNotMatch()));
5013 Assert(this->dof_handler->n_dofs() == global_destination.m(),
5014 (typename std::decay_t<decltype(*this)>::ExcMatrixDoesNotMatch()));
5015 Assert(this->dof_handler->n_dofs() == global_destination.n(),
5016 (typename std::decay_t<decltype(*this)>::ExcMatrixDoesNotMatch()));
5017
5018 Assert(!this->has_children(), ExcMessage("Cell must be active."));
5019
5020 const unsigned int n_dofs = local_source.m();
5021
5022 internal::DoFAccessorImplementation::Implementation::dof_index_vector_type
5023 dof_indices(n_dofs);
5024 internal::DoFAccessorImplementation::get_cell_dof_indices(
5025 *this, dof_indices, this->active_fe_index());
5026
5027 // distribute cell matrix
5028 for (unsigned int i = 0; i < n_dofs; ++i)
5029 global_destination.add(dof_indices[i],
5030 n_dofs,
5031 dof_indices.data(),
5032 &local_source(i, 0));
5033 }
5034
5035
5036
5037 template <int dimension_, int space_dimension_, bool level_dof_access>
5038 template <typename number, typename OutputMatrix, typename OutputVector>
5039 inline void
5040 DoFCellAccessor<dimension_, space_dimension_, level_dof_access>::
5041 distribute_local_to_global(const FullMatrix<number> &local_matrix,
5042 const Vector<number> &local_vector,
5043 OutputMatrix &global_matrix,
5044 OutputVector &global_vector) const
5045 {
5046 Assert(this->dof_handler != nullptr,
5047 (typename std::decay_t<decltype(*this)>::ExcInvalidObject()));
5048 Assert(local_matrix.m() == this->get_fe().n_dofs_per_cell(),
5049 (typename std::decay_t<decltype(*this)>::ExcMatrixDoesNotMatch()));
5050 Assert(local_matrix.n() == this->get_fe().n_dofs_per_cell(),
5051 (typename std::decay_t<decltype(*this)>::ExcVectorDoesNotMatch()));
5052 Assert(this->dof_handler->n_dofs() == global_matrix.m(),
5053 (typename std::decay_t<decltype(*this)>::ExcMatrixDoesNotMatch()));
5054 Assert(this->dof_handler->n_dofs() == global_matrix.n(),
5055 (typename std::decay_t<decltype(*this)>::ExcMatrixDoesNotMatch()));
5056 Assert(local_vector.size() == this->get_fe().n_dofs_per_cell(),
5057 (typename std::decay_t<decltype(*this)>::ExcVectorDoesNotMatch()));
5058 Assert(this->dof_handler->n_dofs() == global_vector.size(),
5059 (typename std::decay_t<decltype(*this)>::ExcVectorDoesNotMatch()));
5060
5061 Assert(!this->has_children(), ExcMessage("Cell must be active."));
5062
5063 const unsigned int n_dofs = this->get_fe().n_dofs_per_cell();
5064 internal::DoFAccessorImplementation::Implementation::dof_index_vector_type
5065 dof_indices(n_dofs);
5066 internal::DoFAccessorImplementation::get_cell_dof_indices(
5067 *this, dof_indices, this->active_fe_index());
5068
5069 // distribute cell matrices
5070 for (unsigned int i = 0; i < n_dofs; ++i)
5071 {
5072 global_matrix.add(dof_indices[i],
5073 n_dofs,
5074 dof_indices.data(),
5075 &local_matrix(i, 0));
5076 global_vector(dof_indices[i]) += local_vector(i);
5077 }
5078 }
5079
5080
5081
5082 DEAL_II_NAMESPACE_CLOSE
5083
5084
5085 #endif