Debian Codegraph @

include/deal.II/grid/tria.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_tria_h
16 #define dealii_tria_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/geometry_info.h>
23 #include <deal.II/base/iterator_range.h>
24 #include <deal.II/base/observer_pointer.h>
25 #include <deal.II/base/partitioner.h>
26 #include <deal.II/base/point.h>
27
28 #include <deal.II/grid/cell_id.h>
29 #include <deal.II/grid/cell_status.h>
30 #include <deal.II/grid/tria_accessor.h>
31 #include <deal.II/grid/tria_iterator_selector.h>
32 #include <deal.II/grid/tria_levels.h>
33
34 #include <boost/range/iterator_range_core.hpp>
35 #include <boost/serialization/map.hpp>
36 #include <boost/serialization/split_member.hpp>
37 #include <boost/serialization/unique_ptr.hpp>
38 #include <boost/serialization/vector.hpp>
39 #include <boost/signals2.hpp>
40
41 #include <bitset>
42 #include <functional>
43 #include <list>
44 #include <map>
45 #include <memory>
46 #include <numeric>
47 #include <vector>
48
49
50 DEAL_II_NAMESPACE_OPEN
51
52 #ifdef signals
53 # error \
54 "The name 'signals' is already defined. You are most likely using the QT library \
55 and using the 'signals' keyword. You can either #include the Qt headers (or any conflicting headers) \
56 *after* the deal.II headers or you can define the 'QT_NO_KEYWORDS' macro and use the 'Q_SIGNALS' macro."
57 #endif
58
59 // Forward declarations
60 #ifndef DOXYGEN
61 template <int dim, int spacedim>
62 class Manifold;
63
64 template <int dim>
65 struct CellData;
66
67 struct SubCellData;
68
69 namespace TriangulationDescription
70 {
71 template <int, int>
72 struct Description;
73 }
74
75 namespace GridTools
76 {
77 template <typename CellIterator>
78 struct PeriodicFacePair;
79 }
80
81 template <int, int, int>
82 class TriaAccessor;
83 template <int spacedim>
84 class TriaAccessor<0, 1, spacedim>;
85 template <int, int, int>
86 class TriaAccessorBase;
87
88 namespace internal
89 {
90 namespace TriangulationImplementation
91 {
92 class TriaFaces;
93
94 class TriaObjects;
95
96 template <int, int>
97 class Policy;
98
99 /**
100 * Forward declaration of a class into which we put much of the
101 * implementation of the Triangulation class. See the .cc file for more
102 * information.
103 */
104 struct Implementation;
105 struct ImplementationMixedMesh;
106 } // namespace TriangulationImplementation
107
108 namespace TriaAccessorImplementation
109 {
110 struct Implementation;
111 }
112 } // namespace internal
113 #endif
114
115
116 /*------------------------------------------------------------------------*/
117
118
119 namespace internal
120 {
121 /**
122 * A namespace for classes internal to the triangulation classes and
123 * helpers.
124 */
125 namespace TriangulationImplementation
126 {
127 /**
128 * Cache class used to store the number of used and active elements (lines
129 * or quads etc) within the levels of a triangulation. This is only the
130 * declaration of the template, concrete instantiations are below.
131 *
132 * In the old days, whenever one wanted to access one of these numbers,
133 * one had to perform a loop over all lines, e.g., and count the elements
134 * until we hit the end iterator. This is time consuming and since access
135 * to the number of lines etc is a rather frequent operation, this was not
136 * an optimal solution.
137 */
138 template <int dim>
139 struct NumberCache
140 {};
141
142 /**
143 * Cache class used to store the number of used and active elements (lines
144 * or quads etc) within the levels of a triangulation. This specialization
145 * stores the numbers of lines.
146 *
147 * In the old days, whenever one wanted to access one of these numbers,
148 * one had to perform a loop over all lines, e.g., and count the elements
149 * until we hit the end iterator. This is time consuming and since access
150 * to the number of lines etc is a rather frequent operation, this was not
151 * an optimal solution.
152 */
153 template <>
154 struct NumberCache<1>
155 {
156 /**
157 * The number of levels on which we have used objects.
158 */
159 unsigned int n_levels;
160
161 /**
162 * Number of used lines in the whole triangulation.
163 */
164 unsigned int n_lines;
165
166 /**
167 * Array holding the number of used lines on each level.
168 */
169 std::vector<unsigned int> n_lines_level;
170
171 /**
172 * Number of active lines in the whole triangulation.
173 */
174 unsigned int n_active_lines;
175
176 /**
177 * Array holding the number of active lines on each level.
178 */
179 std::vector<unsigned int> n_active_lines_level;
180
181 /**
182 * Partitioner for the global active cell indices.
183 */
184 std::shared_ptr<const Utilities::MPI::Partitioner>
185 active_cell_index_partitioner;
186
187 /**
188 * Partitioner for the global level cell indices for each level.
189 */
190 std::vector<std::shared_ptr<const Utilities::MPI::Partitioner>>
191 level_cell_index_partitioners;
192
193 /**
194 * Constructor. Set values to zero by default.
195 */
196 NumberCache();
197
198 /**
199 * Determine an estimate for the memory consumption (in bytes) of this
200 * object.
201 */
202 std::size_t
203 memory_consumption() const;
204
205 /**
206 * Read or write the data of this object to or from a stream for the
207 * purpose of serialization using the [BOOST serialization
208 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
209 */
210 template <class Archive>
211 void
212 serialize(Archive &ar, const unsigned int version);
213 };
214
215
216 /**
217 * Cache class used to store the number of used and active elements (lines
218 * or quads etc) within the levels of a triangulation. This specialization
219 * stores the numbers of quads. Due to the inheritance from the base class
220 * NumberCache<1>, the numbers of lines are also within this class.
221 *
222 * In the old days, whenever one wanted to access one of these numbers,
223 * one had to perform a loop over all lines, e.g., and count the elements
224 * until we hit the end iterator. This is time consuming and since access
225 * to the number of lines etc is a rather frequent operation, this was not
226 * an optimal solution.
227 */
228 template <>
229 struct NumberCache<2> : public NumberCache<1>
230 {
231 /**
232 * Number of used quads in the whole triangulation.
233 */
234 unsigned int n_quads;
235
236 /**
237 * Array holding the number of used quads on each level.
238 */
239 std::vector<unsigned int> n_quads_level;
240
241 /**
242 * Number of active quads in the whole triangulation.
243 */
244 unsigned int n_active_quads;
245
246 /**
247 * Array holding the number of active quads on each level.
248 */
249 std::vector<unsigned int> n_active_quads_level;
250
251 /**
252 * Constructor. Set values to zero by default.
253 */
254 NumberCache();
255
256 /**
257 * Determine an estimate for the memory consumption (in bytes) of this
258 * object.
259 */
260 std::size_t
261 memory_consumption() const;
262
263 /**
264 * Read or write the data of this object to or from a stream for the
265 * purpose of serialization using the [BOOST serialization
266 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
267 */
268 template <class Archive>
269 void
270 serialize(Archive &ar, const unsigned int version);
271 };
272
273
274 /**
275 * Cache class used to store the number of used and active elements (lines
276 * or quads etc) within the levels of a triangulation. This specialization
277 * stores the numbers of hexes. Due to the inheritance from the base class
278 * NumberCache<2>, the numbers of lines and quads are also within this
279 * class.
280 *
281 * In the old days, whenever one wanted to access one of these numbers,
282 * one had to perform a loop over all lines, e.g., and count the elements
283 * until we hit the end . This is time consuming and since access to the
284 * number of lines etc is a rather frequent operation, this was not an
285 * optimal solution.
286 */
287 template <>
288 struct NumberCache<3> : public NumberCache<2>
289 {
290 /**
291 * Number of used hexes in the whole triangulation.
292 */
293 unsigned int n_hexes;
294
295 /**
296 * Array holding the number of used hexes on each level.
297 */
298 std::vector<unsigned int> n_hexes_level;
299
300 /**
301 * Number of active hexes in the whole triangulation.
302 */
303 unsigned int n_active_hexes;
304
305 /**
306 * Array holding the number of active hexes on each level.
307 */
308 std::vector<unsigned int> n_active_hexes_level;
309
310 /**
311 * Constructor. Set values to zero by default.
312 */
313 NumberCache();
314
315 /**
316 * Determine an estimate for the memory consumption (in bytes) of this
317 * object.
318 */
319 std::size_t
320 memory_consumption() const;
321
322 /**
323 * Read or write the data of this object to or from a stream for the
324 * purpose of serialization using the [BOOST serialization
325 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
326 */
327 template <class Archive>
328 void
329 serialize(Archive &ar, const unsigned int version);
330 };
331 } // namespace TriangulationImplementation
332
333
334 /**
335 * A structure that binds information about data attached to cells.
336 */
337 template <int dim, int spacedim = dim>
338 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
339 struct CellAttachedData
340 {
341 using cell_iterator = TriaIterator<CellAccessor<dim, spacedim>>;
342
343 /**
344 * Number of functions that get attached to the Triangulation through
345 * register_data_attach() for example SolutionTransfer.
346 */
347 unsigned int n_attached_data_sets;
348
349 /**
350 * Number of functions that need to unpack their data after a call from
351 * load().
352 */
353 unsigned int n_attached_deserialize;
354
355 using pack_callback_t =
356 std::function<std::vector<char>(cell_iterator, CellStatus)>;
357
358 /**
359 * These callback functions will be stored in the order in which they
360 * have been registered with the register_data_attach() function.
361 */
362 std::vector<pack_callback_t> pack_callbacks_fixed;
363 std::vector<pack_callback_t> pack_callbacks_variable;
364 };
365
366 /**
367 * A structure that stores information about the data that has been, or
368 * will be, attached to cells via the register_data_attach() function
369 * and later retrieved via notify_ready_to_unpack().
370 *
371 * This internal class is dedicated to the data serialization and transfer
372 * across repartitioned meshes and to/from the file system.
373 *
374 * It is designed to store all data buffers intended for serialization.
375 */
376 template <int dim, int spacedim = dim>
377 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
378 class CellAttachedDataSerializer
379 {
380 public:
381 using cell_iterator = TriaIterator<CellAccessor<dim, spacedim>>;
382
383 /**
384 * Version number stored in the .info file written by
385 * Triangulation::save().
386 */
387 static inline constexpr unsigned int version_number = 5;
388
389 /**
390 * Auxiliary data structure for assigning a CellStatus to a deal.II cell
391 * iterator. For an extensive description of the former, see the
392 * documentation for the member function register_data_attach().
393 */
394 using cell_relation_t = typename std::pair<cell_iterator, CellStatus>;
395
396 CellAttachedDataSerializer();
397
398 /**
399 * Prepare data serialization by calling the pack callback functions on each
400 * cell in @p cell_relations.
401 *
402 * All registered callback functions in @p pack_callbacks_fixed will write
403 * into the fixed size buffer, whereas each entry of @p pack_callbacks_variable
404 * will write its data into the variable size buffer.
405 */
406 void
407 pack_data(
408 const std::vector<cell_relation_t> &cell_relations,
409 const std::vector<
410 typename internal::CellAttachedData<dim, spacedim>::pack_callback_t>
411 &pack_callbacks_fixed,
412 const std::vector<
413 typename internal::CellAttachedData<dim, spacedim>::pack_callback_t>
414 &pack_callbacks_variable,
415 const MPI_Comm &mpi_communicator);
416
417 /**
418 * Unpack the CellStatus information on each entry of
419 * @p cell_relations.
420 *
421 * Data has to be previously transferred with execute_transfer()
422 * or deserialized from the file system via load().
423 */
424 void
425 unpack_cell_status(std::vector<cell_relation_t> &cell_relations) const;
426
427 /**
428 * Unpack previously serialized data on each cell registered in
429 * @p cell_relations with the provided @p unpack_callback function.
430 *
431 * The parameter @p handle corresponds to the position where the
432 * @p unpack_callback function is allowed to read from the memory. Its
433 * value needs to be in accordance with the corresponding pack_callback
434 * function that has been registered previously.
435 *
436 * Data has to be previously transferred with execute_transfer()
437 * or deserialized from the file system via load().
438 */
439 void
440 unpack_data(
441 const std::vector<cell_relation_t> &cell_relations,
442 const unsigned int handle,
443 const std::function<
444 void(const cell_iterator &,
445 const CellStatus &,
446 const boost::iterator_range<std::vector<char>::const_iterator> &)>
447 &unpack_callback) const;
448
449 /**
450 * Serialize data to file system.
451 *
452 * The data will be written in a number of file whose names
453 * consists of the stem @p file_basename and an attached identifier
454 * <tt>_fixed.data</tt> for fixed size data and <tt>_variable.data</tt>
455 * for variable size data.
456 *
457 * If MPI support is enabled, all processors write into these files
458 * simultaneously via MPI I/O. Each processor's position to write to will be
459 * determined from the provided input parameters.
460 *
461 * Data has to be previously packed with pack_data().
462 */
463 void
464 save(const unsigned int global_first_cell,
465 const unsigned int global_num_cells,
466 const std::string &file_basename,
467 const MPI_Comm &mpi_communicator) const;
468
469 /**
470 * Deserialize data from file system.
471 *
472 * The data will be read from separate files whose names
473 * consists of the stem @p file_basename and an attached identifier
474 * <tt>_fixed.data</tt> for fixed size data and <tt>_variable.data</tt>
475 * for variable size data.
476 * The @p n_attached_deserialize_fixed and @p n_attached_deserialize_variable
477 * parameters are required to gather the memory offsets for each
478 * callback.
479 *
480 * If MPI support is enabled, all processors read from these files
481 * simultaneously via MPIIO. Each processor's position to read from will be
482 * determined from the provided input arguments.
483 *
484 * After loading, unpack_data() needs to be called to finally
485 * distribute data across the associated triangulation.
486 */
487 void
488 load(const unsigned int global_first_cell,
489 const unsigned int global_num_cells,
490 const unsigned int local_num_cells,
491 const std::string &file_basename,
492 const unsigned int n_attached_deserialize_fixed,
493 const unsigned int n_attached_deserialize_variable,
494 const MPI_Comm &mpi_communicator);
495
496 /**
497 * Clears all containers and associated data, and resets member
498 * values to their default state.
499 *
500 * Frees memory completely.
501 */
502 void
503 clear();
504
505 /**
506 * Flag that denotes if variable size data has been packed.
507 */
508 bool variable_size_data_stored;
509
510 /**
511 * Cumulative size in bytes that those functions that have called
512 * register_data_attach() want to attach to each cell. This number
513 * only pertains to fixed-sized buffers where the data attached to
514 * each cell has exactly the same size.
515 *
516 * The last entry of this container corresponds to the data size
517 * packed per cell in the fixed size buffer (which can be accessed
518 * calling <tt>sizes_fixed_cumulative.back()</tt>).
519 */
520 std::vector<unsigned int> sizes_fixed_cumulative;
521
522 /**
523 * Consecutive buffers designed for the fixed size serialization
524 * functions.
525 */
526 std::vector<char> src_data_fixed;
527 std::vector<char> dest_data_fixed;
528
529 /**
530 * Consecutive buffers designed for the variable size serialization
531 * functions.
532 */
533 std::vector<int> src_sizes_variable;
534 std::vector<int> dest_sizes_variable;
535 std::vector<char> src_data_variable;
536 std::vector<char> dest_data_variable;
537 };
538 } // namespace internal
539
540
541 /*------------------------------------------------------------------------*/
542
543
544 /**
545 * A triangulation is a collection of cells that, jointly, cover the domain
546 * on which one typically wants to solve a partial differential equation.
547 * This domain, and the mesh that covers it, represents a @p dim -dimensional manifold
548 * and lives in @p spacedim spatial dimensions, where @p dim and @p spacedim
549 * are the template arguments of this class. (If @p spacedim is not specified,
550 * it takes the default value `spacedim=dim`.)
551 *
552 * Thus, for example, an object of type @p Triangulation<1,1> (or simply @p
553 * Triangulation<1> since @p spacedim==dim by default) is used to represent
554 * and handle the usual one-dimensional triangulation used in the finite
555 * element method (so, segments on a straight line). On the other hand,
556 * objects such as @p Triangulation<1,2> or @p Triangulation<2,3> (that are
557 * associated with curves in 2d or surfaces in 3d) are the ones one wants to
558 * use in the boundary element method.
559 *
560 * The name of the class is mostly historical and is not meant to imply that
561 * a Triangulation can only consist of triangles. Instead, triangulations
562 * will consist of line segments in 1d (i.e., if `dim==1`), and of
563 * three-dimensional cells (if `dim==3`). Moreover, historically, deal.II only
564 * supported quadrilaterals (cells with four vertices: deformed rectangles) in
565 * 2d and hexahedra (cells with six sides and eight vertices that are deformed
566 * boxes), neither of which are triangles. In other words, the term
567 * "triangulation" in the deal.II language is synonymous with "mesh" and is
568 * to be understood separate from its linguistic origin.
569 *
570 * This class is written to be as independent of the dimension as possible
571 * (thus the complex construction of the
572 * dealii::internal::TriangulationImplementation::TriaLevel classes) to allow
573 * code-sharing, to allow reducing the need to mirror changes in the code for
574 * one dimension to the code for other dimensions. Nonetheless, some of the
575 * functions are dependent of the dimension and there only exist specialized
576 * versions for distinct dimensions.
577 *
578 * This class satisfies the
579 * @ref ConceptMeshType "MeshType concept"
580 * requirements.
581 *
582 * <h3>Structure and iterators</h3>
583 *
584 * The actual data structure of a Triangulation object is rather complex and
585 * quite inconvenient if one attempted to operate on it directly, since data
586 * is spread over quite a lot of arrays and other places. However, there are
587 * ways powerful enough to work on these data structures without knowing their
588 * exact relations. deal.II uses class local alias (see below) to make
589 * things as easy and dimension independent as possible.
590 *
591 * The Triangulation class provides iterators which enable looping over all
592 * cells without knowing the exact representation used to describe them. For
593 * more information see the documentation of <tt>TriaIterator</tt>. Their
594 * names are alias imported from the Iterators class (thus making them
595 * local types to this class) and are as follows:
596 *
597 * <ul>
598 * <li> <tt>cell_iterator</tt>: loop over all cells used in the Triangulation
599 * <li> <tt>active_cell_iterator</tt>: loop over all active cells
600 * </ul>
601 *
602 * For <tt>dim==1</tt>, these iterators are mapped as follows:
603 * @code
604 * using cell_iterator = line_iterator;
605 * using active_cell_iterator = active_line_iterator;
606 * @endcode
607 * while for @p dim==2 we have the additional face iterator:
608 * @code
609 * using cell_iterator = quad_iterator;
610 * using active_cell_iterator = active_quad_iterator;
611 *
612 * using face_iterator = line_iterator;
613 * using active_face_iterator = active_line_iterator;
614 * @endcode
615 *
616 * By using the cell iterators, you can write code independent of the spatial
617 * dimension. The same applies for substructure iterators, where a
618 * substructure is defined as a face of a cell. The face of a cell is a vertex
619 * in 1d and a line in 2d; however, vertices are handled in a different way
620 * and therefore lines have no faces.
621 *
622 * The Triangulation class offers functions like begin_active() which gives
623 * you an iterator to the first active cell. There are quite a lot of
624 * functions returning iterators. Take a look at the class doc to get an
625 * overview.
626 *
627 * Usage of these iterators is similar to usage of standard container
628 * iterators. Some examples taken from the Triangulation source code follow
629 * (notice that in the last two examples the template parameter @p spacedim
630 * has been omitted, so it takes the default value <code>dim</code>).
631 *
632 * <ul>
633 * <li> <em>Counting the number of cells on a specific level</em>
634 * @code
635 * template <int dim, int spacedim>
636 * unsigned int
637 * Triangulation<dim, spacedim>::n_cells (const int level) const
638 * {
639 * int n=0;
640 * for (const auto &cell : cell_iterators_on_level(level))
641 * ++n;
642 * return n;
643 * }
644 * @endcode
645 * Another way, which uses <tt>std::distance</tt>, would be to write
646 * @code
647 * template <int dim>
648 * unsigned int
649 * Triangulation<dim>::n_cells (const int level) const
650 * {
651 * int n=0;
652 * distance (begin(level),
653 * (level == levels.size()-1 ?
654 * cell_iterator(end()) :
655 * begin (level+1)),
656 * n);
657 * return n;
658 * }
659 * @endcode
660 *
661 * <li> <em>Refining all cells of a triangulation</em>
662 * @code
663 * template <int dim>
664 * void Triangulation<dim>::refine_global ()
665 * {
666 * for (const auto &cell : active_cell_iterators())
667 * cell->set_refine_flag ();
668 * execute_coarsening_and_refinement ();
669 * }
670 * @endcode
671 * </ul>
672 *
673 *
674 * <h3>Usage</h3>
675 *
676 * Usage of a Triangulation is mainly done through the use of iterators. An
677 * example probably shows best how to use it:
678 * @code
679 * int main ()
680 * {
681 * Triangulation<2> tria;
682 *
683 * // read in a coarse grid file
684 *
685 * // we want to log the refinement history
686 * ofstream history ("mesh.history");
687 *
688 * // refine first cell
689 * tria.begin_active()->set_refine_flag();
690 * tria.save_refine_flags (history);
691 * tria.execute_coarsening_and_refinement ();
692 *
693 * // refine first active cell on coarsest level
694 * tria.begin_active()->set_refine_flag ();
695 * tria.save_refine_flags (history);
696 * tria.execute_coarsening_and_refinement ();
697 *
698 * Triangulation<2>::active_cell_iterator cell;
699 * for (int i=0; i<17; ++i)
700 * {
701 * // refine the presently second last cell 17 times
702 * cell = tria.last_active(tria.n_levels()-1);
703 * --cell;
704 * cell->set_refine_flag ();
705 * tria.save_refine_flags (history);
706 * tria.execute_coarsening_and_refinement ();
707 * };
708 * // output the grid
709 * ofstream out("grid.1");
710 * GridOut::write_gnuplot (tria, out);
711 * }
712 * @endcode
713 *
714 *
715 * <h3>Creating a triangulation</h3>
716 *
717 * There are several possibilities to create a triangulation:
718 * <ul>
719 * <li> The most common domains, such as hypercubes (i.e. lines, squares,
720 * cubes, etc), hyper-balls (circles, balls, ...) and some other, more weird
721 * domains such as the L-shape region and higher dimensional generalizations
722 * and others, are provided by the GridGenerator class which takes a
723 * triangulation and fills it by a division of the required domain.
724 *
725 * <li> Reading in a triangulation: By using an object of the GridIn class,
726 * you can read in fairly general triangulations. See there for more
727 * information. The mentioned class uses the interface described directly
728 * below to transfer the data into the triangulation.
729 *
730 * <li> Explicitly creating a triangulation: you can create a triangulation by
731 * providing a list of vertices and a list of cells. Each such cell consists
732 * of a vector storing the indices of the vertices of this cell in the vertex
733 * list. To see how this works, you can take a look at the GridIn<dim>::read_*
734 * functions. The appropriate function to be called is create_triangulation().
735 *
736 * Creating the hierarchical information needed for this library from cells
737 * storing only vertex information can be quite a complex task. For example
738 * in 2d, we have to create lines between vertices (but only once, though
739 * there are two cells which link these two vertices) and we have to create
740 * neighborhood information. Grids being read in should therefore not be too
741 * large, reading refined grids would be inefficient (although there is
742 * technically no problem in reading grids with several 10.000 or 100.000
743 * cells; the library can handle this without much problems). Apart from the
744 * performance aspect, refined grids do not lend too well to multigrid
745 * algorithms, since solving on the coarsest level is expensive. It is wiser
746 * in any case to read in a grid as coarse as possible and then do the needed
747 * refinement steps.
748 *
749 * It is your duty to guarantee that cells have the correct orientation. To
750 * guarantee this, in the input vector keeping the cell list, the vertex
751 * indices for each cell have to be in a defined order, see the documentation
752 * of GeometryInfo<dim>. In one dimension, the first vertex index must refer
753 * to that vertex with the lower coordinate value. In 2d and 3d, the
754 * corresponding conditions are not easy to verify and no full attempt to do
755 * so is made. If you violate this condition, you may end up with matrix
756 * entries having the wrong sign (clockwise vertex numbering, which results in
757 * a negative area element) of with wrong matrix elements (twisted
758 * quadrilaterals, i.e. two vertices interchanged; this results in a wrong
759 * area element).
760 *
761 * There are more subtle conditions which must be imposed upon the vertex
762 * numbering within cells. They do not only hold for the data read from an UCD
763 * or any other input file, but also for the data passed to
764 * create_triangulation(). See the documentation for the GridIn class for more
765 * details on this, and above all to the GridTools::consistently_order_cells()
766 * function that explains many of the problems and an algorithm to reorder cells
767 * such that they satisfy the conditions outlined above.
768 *
769 * <li> Copying a triangulation: when computing on time dependent meshes or
770 * when using adaptive refinement, you will often want to create a new
771 * triangulation to be the same as another one. This is facilitated by the @p
772 * copy_triangulation function.
773 *
774 * It is guaranteed that vertex, line or cell numbers in the two
775 * triangulations are the same and that two iterators walking on the two
776 * triangulations visit matching cells if they are incremented in parallel. It
777 * may be conceivable to implement a clean-up in the copy operation, which
778 * eliminates holes of unused memory, re-joins scattered data and so on. In
779 * principle this would be a useful operation but guaranteeing some
780 * parallelism in the two triangulations seems more important since usually
781 * data will have to be transferred between the grids.
782 * </ul>
783 *
784 *
785 * <h3>Refinement and coarsening of a triangulation</h3>
786 *
787 * Refinement of a triangulation may be done through several ways. The most
788 * low-level way is directly through iterators: let @p i be an iterator to an
789 * active cell (i.e. the cell pointed to has no children), then the function
790 * call <tt>i->set_refine_flag()</tt> marks the respective cell for
791 * refinement. Marking non-active cells results in an error.
792 *
793 * After all the cells you wanted to mark for refinement, call
794 * execute_coarsening_and_refinement() to actually perform the refinement.
795 * This function itself first calls the @p prepare_coarsening_and_refinement
796 * function to regularize the resulting triangulation: since a face between
797 * two adjacent cells may only be subdivided once (i.e. the levels of two
798 * adjacent cells may differ by one at most; it is not possible to have a cell
799 * refined twice while the neighboring one is not refined), some additional
800 * cells are flagged for refinement to smooth the grid. This enlarges the
801 * number of resulting cells but makes the grid more regular, thus leading to
802 * better approximation properties and, above all, making the handling of data
803 * structures and algorithms much easier. To be honest, this is mostly an
804 * algorithmic step than one needed by the finite element method.
805 *
806 * To coarsen a grid, the same way as above is possible by using
807 * <tt>i->set_coarsen_flag</tt> and calling
808 * execute_coarsening_and_refinement().
809 *
810 * The reason for first coarsening, then refining is that the refinement
811 * usually adds some additional cells to keep the triangulation regular and
812 * thus satisfies all refinement requests, while the coarsening does not
813 * delete cells not requested for; therefore the refinement will often revert
814 * some effects of coarsening while the opposite is not true. The stated order
815 * of coarsening before refinement will thus normally lead to a result closer
816 * to the intended one.
817 *
818 * Marking cells for refinement 'by hand' through iterators is one way to
819 * produce a new grid, especially if you know what kind of grid you are
820 * looking for, e.g. if you want to have a grid successively refined towards
821 * the boundary or always at the center (see the example programs, they do
822 * exactly these things). There are more advanced functions, however, which
823 * are more suitable for automatic generation of hierarchical grids in the
824 * context of a posteriori error estimation and adaptive finite elements.
825 * These functions can be found in the GridRefinement class.
826 *
827 *
828 * <h3>Smoothing of a triangulation</h3>
829 *
830 * Some degradation of approximation properties has been observed for grids
831 * which are too unstructured. Therefore, prepare_coarsening_and_refinement()
832 * which is automatically called by execute_coarsening_and_refinement() can do
833 * some smoothing of the triangulation. Note that mesh smoothing is only done
834 * for two or more space dimensions, no smoothing is available at present for
835 * one spatial dimension. In the following, let <tt>execute_*</tt> stand for
836 * execute_coarsening_and_refinement().
837 *
838 * For the purpose of smoothing, the Triangulation constructor takes an
839 * argument specifying whether a smoothing step shall be performed on the grid
840 * each time <tt>execute_*</tt> is called. The default is that such a step not
841 * be done, since this results in additional cells being produced, which may
842 * not be necessary in all cases. If switched on, calling <tt>execute_*</tt>
843 * results in flagging additional cells for refinement to avoid vertices as
844 * the ones mentioned. The algorithms for both regularization and smoothing of
845 * triangulations are described below in the section on technical issues. The
846 * reason why this parameter must be given to the constructor rather than to
847 * <tt>execute_*</tt> is that it would result in algorithmic problems if you
848 * called <tt>execute_*</tt> once without and once with smoothing, since then
849 * in some refinement steps would need to be refined twice.
850 *
851 * The parameter taken by the constructor is an integer which may be composed
852 * bitwise by the constants defined in the enum #MeshSmoothing (see there for
853 * the possibilities).
854 *
855 * @note While it is possible to pass all of the flags in #MeshSmoothing to
856 * objects of type parallel::distributed::Triangulation, it is not always
857 * possible to honor all of these smoothing options if they would require
858 * knowledge of refinement/coarsening flags on cells not locally owned by this
859 * processor. As a consequence, for some of these flags, the ultimate number
860 * of cells of the parallel triangulation may depend on the number of
861 * processors into which it is partitioned.
862 *
863 *
864 * <h3>Material and boundary information</h3>
865 *
866 * Each cell, face or edge stores information denoting the material or the
867 * part of the boundary that an object belongs to. The material id of a cell
868 * is typically used to identify which cells belong to a particular part of
869 * the domain, e.g., when you have different materials (steel, concrete, wood)
870 * that are all part of the same domain. One would then usually query the
871 * material id associated with a cell during assembly of the bilinear form,
872 * and use it to determine (e.g., by table lookup, or a sequence of if-else
873 * statements) what the correct material coefficients would be for that cell.
874 * See also
875 * @ref GlossMaterialId "this glossary entry".
876 *
877 * This material_id may be set upon construction of a triangulation (through
878 * the CellData data structure), or later through use of cell iterators. For a
879 * typical use of this functionality, see the step-28 tutorial program. The
880 * functions of the GridGenerator namespace typically set the material ID of
881 * all cells to zero. When reading a triangulation through the GridIn class,
882 * different input file formats have different conventions, but typically
883 * either explicitly specify the material id, or if they don't, then GridIn
884 * simply sets them to zero. Because the material of a cell is intended
885 * to pertain to a particular region of the domain, material ids are inherited
886 * by child cells from their parent upon mesh refinement.
887 *
888 * Boundary indicators on lower dimensional objects (these have no material
889 * id) indicate the number of a boundary component. The weak formulation of the
890 * partial differential equation may have different boundary conditions on
891 * different parts of the boundary. The boundary indicator can be used in
892 * creating the matrix or the right hand side vector to indicate these
893 * different parts of the model (this use is like the material id of cells).
894 * Boundary indicators may be in the range from zero to
895 * numbers::internal_face_boundary_id-1. The value
896 * numbers::internal_face_boundary_id is reserved to denote interior lines (in
897 * 2d) and interior lines and quads (in 3d), which do not have a boundary
898 * indicator. This way, a program can easily determine, whether such an object
899 * is at the boundary or not. Material indicators may be in the range from
900 * zero to numbers::invalid_material_id-1.
901 *
902 * Lines in two dimensions and quads in three dimensions inherit their
903 * boundary indicator to their children upon refinement. You should therefore
904 * make sure that if you have different boundary parts, the different parts
905 * are separated by a vertex (in 2d) or a line (in 3d) such that each boundary
906 * line or quad has a unique boundary indicator.
907 *
908 * By default (unless otherwise specified during creation of a triangulation),
909 * all parts of the boundary have boundary indicator zero. As a historical
910 * wart, this isn't true for 1d meshes, however: For these, leftmost vertices
911 * have boundary indicator zero while rightmost vertices have boundary
912 * indicator one. In either case, the boundary indicator of a face can be
913 * changed using a call of the kind
914 * <code>cell-@>face(1)-@>set_boundary_id(42);</code>.
915 *
916 * @see
917 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
918 *
919 *
920 * <h3>History of a triangulation</h3>
921 *
922 * It is possible to reconstruct a grid from its refinement history, which can
923 * be stored and loaded through the @p save_refine_flags and @p
924 * load_refine_flags functions. Normally, the code will look like this:
925 * @code
926 * // open output file
927 * std::ofstream history("mesh.history");
928 * // do 10 refinement steps
929 * for (unsigned int step=0; step<10; ++step)
930 * {
931 * ...;
932 * // flag cells according to some criterion
933 * ...;
934 * tria.save_refine_flags (history);
935 * tria.execute_coarsening_and_refinement ();
936 * }
937 * @endcode
938 *
939 * If you want to re-create the grid from the stored information, you write:
940 * @code
941 * // open input file
942 * std::ifstream history("mesh.history");
943 * // do 10 refinement steps
944 * for (unsigned int step=0; step<10; ++step)
945 * {
946 * tria.load_refine_flags (history);
947 * tria.execute_coarsening_and_refinement ();
948 * }
949 * @endcode
950 *
951 * The same scheme is employed for coarsening and the coarsening flags.
952 *
953 * You may write other information to the output file between different sets
954 * of refinement information, as long as you read it upon re-creation of the
955 * grid. You should make sure that the other information in the new
956 * triangulation which is to be created from the saved flags, matches that of
957 * the old triangulation, for example the smoothing level; if not, the cells
958 * actually created from the flags may be other ones, since smoothing adds
959 * additional cells, but their number may be depending on the smoothing level.
960 *
961 * There actually are two sets of <tt>save_*_flags</tt> and
962 * <tt>load_*_flags</tt> functions. One takes a stream as argument and
963 * reads/writes the information from/to the stream, thus enabling storing
964 * flags to files. The other set takes an argument of type
965 * <tt>vector<bool></tt>. This enables the user to temporarily store some
966 * flags, e.g. if another function needs them, and restore them afterwards.
967 *
968 *
969 * <h3>User flags and data</h3>
970 *
971 * A triangulation offers one bit per subobject for user flags. This field can
972 * be accessed as all other data using iterators. Normally, this user flag is
973 * used if an algorithm walks over all cells and needs information whether
974 * another cell, e.g. a neighbor, has already been processed.
975 * See @ref GlossUserFlags "the glossary for more information".
976 *
977 * There is another set of user data, which can be either an <tt>unsigned
978 * int</tt> or a <tt>void *</tt>, for each subobject. You can access
979 * these through the functions listed under <tt>User data</tt> in the accessor
980 * classes. Again, see
981 * @ref GlossUserData "the glossary for more information".
982 *
983 * The value of these user indices or pointers is @p nullptr by default. Note
984 * that the pointers are not inherited to children upon refinement. Still,
985 * after a remeshing they are available on all cells, where they were set on
986 * the previous mesh.
987 *
988 * The usual warning about the missing type safety of @p void pointers are
989 * obviously in place here; responsibility for correctness of types etc lies
990 * entirely with the user of the pointer.
991 *
992 * @note User pointers and user indices are stored in the same place. In order
993 * to avoid unwanted conversions, Triangulation checks which one of them is in
994 * use and does not allow access to the other one, until clear_user_data() has
995 * been called.
996 *
997 *
998 * <h3>Describing curved geometries</h3>
999 *
1000 * deal.II implements all geometries (curved and otherwise) with classes
1001 * inheriting from Manifold; see the documentation of Manifold, step-49, or
1002 * the
1003 * @ref manifold
1004 * topic for examples and a complete description of the algorithms. By
1005 * default, all cells in a Triangulation have a flat geometry, meaning that
1006 * all lines in the Triangulation are assumed to be straight. If a cell has a
1007 * manifold_id that is not equal to numbers::flat_manifold_id then the
1008 * Triangulation uses the associated Manifold object for computations on that
1009 * cell (e.g., cell refinement). Here is a quick example, taken from the
1010 * implementation of GridGenerator::hyper_ball(), that sets up a polar grid:
1011 *
1012 * @code
1013 * int main ()
1014 * {
1015 * Triangulation<2> triangulation;
1016 * const std::vector<Point<2>> vertices = {{-1.0,-1.0},
1017 * {+1.0,-1.0},
1018 * {-0.5,-0.5},
1019 * {+0.5,-0.5},
1020 * {-0.5,+0.5},
1021 * {+1.0,+1.0},
1022 * {-1.0,+1.0},
1023 * {+1.0,+1.0}};
1024 * const std::vector<std::array<int,GeometryInfo<2>::vertices_per_cell>>
1025 * cell_vertices = {{0, 1, 2, 3},
1026 * {0, 2, 6, 4},
1027 * {2, 3, 4, 5},
1028 * {1, 7, 3, 5},
1029 * {6, 4, 7, 5}};
1030 *
1031 * std::vector<CellData<2>> cells(cell_vertices.size(), CellData<2>());
1032 * for (unsigned int i=0; i<cell_vertices.size(); ++i)
1033 * for (unsigned int j=0; j<GeometryInfo<2>::vertices_per_cell; ++j)
1034 * cells[i].vertices[j] = cell_vertices[i][j];
1035 *
1036 * triangulation.create_triangulation (vertices, cells, SubCellData());
1037 * triangulation.set_all_manifold_ids_on_boundary(42);
1038 *
1039 * // set_manifold stores a copy of its second argument,
1040 * // so a temporary is okay
1041 * triangulation.set_manifold(42, PolarManifold<2>());
1042 * for (unsigned int i = 0; i < 4; ++i)
1043 * {
1044 * // refine all boundary cells
1045 * for (const auto &cell : triangulation.active_cell_iterators())
1046 * if (cell->at_boundary())
1047 * cell->set_refine_flag();
1048 *
1049 * triangulation.execute_coarsening_and_refinement();
1050 * }
1051 * }
1052 * @endcode
1053 *
1054 * This will set up a grid where the boundary lines will be refined by
1055 * performing calculations in polar coordinates. When the mesh is refined the
1056 * cells adjacent to the boundary will use this new line midpoint (as well as
1057 * the other three midpoints and original cell vertices) to calculate the cell
1058 * midpoint with a transfinite interpolation: this propagates the curved
1059 * boundary into the interior in a smooth way. It is possible to generate a
1060 * better grid (which interpolates across all cells between two different
1061 * Manifold descriptions, instead of just going one cell at a time) by using
1062 * TransfiniteInterpolationManifold; see the documentation of that class for
1063 * more information.
1064 *
1065 * You should take note of one caveat: if you have concave boundaries, you
1066 * must make sure that a new boundary vertex does not lie too much inside the
1067 * cell which is to be refined. The reason is that the center vertex is placed
1068 * at the point which is a weighted average of the vertices of the original
1069 * cell, new face midpoints, and (in 3d) new line midpoints. Therefore if your
1070 * new boundary vertex is too near the center of the old quadrilateral or
1071 * hexahedron, the distance to the midpoint vertex will become too small, thus
1072 * generating distorted cells. This issue is discussed extensively in
1073 * @ref GlossDistorted "distorted cells".
1074 *
1075 * <h3>Getting notice when a triangulation changes</h3>
1076 *
1077 * There are cases where one object would like to know whenever a
1078 * triangulation is being refined, copied, or modified in a number of other
1079 * ways. This could of course be achieved if, in your user code, you tell
1080 * every such object whenever you are about to refine the triangulation, but
1081 * this will get tedious and is error prone. The Triangulation class
1082 * implements a more elegant way to achieve this: signals.
1083 *
1084 * In essence, a signal is an object (a member of the Triangulation class)
1085 * that another object can connect to. A connection is in essence that the
1086 * connecting object passes a function object taking a certain number and kind
1087 * of arguments. Whenever the owner of the signal wants to indicate a certain
1088 * kind of event, it 'triggers' the signal, which in turn means that all
1089 * connections of the signal are triggered: in other word, the function
1090 * objects are executed and can take the action that is necessary.
1091 *
1092 * As a simple example, the following code will print something to the output
1093 * every time the triangulation has just been refined:
1094 * @code
1095 * void f()
1096 * {
1097 * std::cout << "Triangulation has been refined." << std::endl;
1098 * }
1099 *
1100 * void run ()
1101 * {
1102 * Triangulation<dim> triangulation;
1103 * // fill it somehow
1104 * triangulation.signals.post_refinement.connect (&f);
1105 * triangulation.refine_global (2);
1106 * }
1107 * @endcode
1108 * This code will produce output twice, once for each refinement cycle.
1109 *
1110 * A more interesting application would be the following, akin to what the
1111 * FEValues class does. This class stores a pointer to a triangulation and
1112 * also an iterator to the cell last handled (so that it can compare the
1113 * current cell with the previous one and, for example, decide that there is
1114 * no need to re-compute the Jacobian matrix if the new cell is a simple
1115 * translation of the previous one). However, whenever the triangulation is
1116 * modified, the iterator to the previously handled cell needs to be
1117 * invalidated since it now no longer points to any useful cell (or, at the
1118 * very least, points to something that may not necessarily resemble the cells
1119 * previously handled). The code would look something like this (the real code
1120 * has some more error checking and has to handle the case that subsequent
1121 * cells might actually belong to different triangulation, but that is of no
1122 * concern to us here):
1123 * @code
1124 * template <int dim>
1125 * class FEValues
1126 * {
1127 * Triangulation<dim>::active_cell_iterator current_cell, previous_cell;
1128 * public:
1129 * void reinit (Triangulation<dim>::active_cell_iterator &cell);
1130 * void invalidate_previous_cell ();
1131 * };
1132 *
1133 * template <int dim>
1134 * void
1135 * FEValues<dim>::reinit (Triangulation<dim>::active_cell_iterator &cell)
1136 * {
1137 * if (previous_cell.status() != valid)
1138 * {
1139 * // previous_cell has not been set. set it now, and register with the
1140 * // triangulation that we want to be informed about mesh refinement
1141 * previous_cell = current_cell;
1142 * previous_cell->get_triangulation().signals.post_refinement.connect(
1143 * [this]()
1144 * {
1145 * this->invalidate_previous_cell();
1146 * });
1147 * }
1148 * else
1149 * previous_cell = current_cell;
1150 *
1151 * current_cell = cell;
1152 * // ... do something with the cell...
1153 * }
1154 *
1155 * template <int dim>
1156 * void
1157 * FEValues<dim>::invalidate_previous_cell ()
1158 * {
1159 * previous_cell = Triangulation<dim>::active_cell_iterator();
1160 * }
1161 * @endcode
1162 * Here, whenever the triangulation is refined, it triggers the
1163 * post-refinement signal which calls the function object attached to it. This
1164 * function object is the member function
1165 * <code>FEValues<dim>::invalidate_previous_cell</code> where we have bound
1166 * the single argument (the <code>this</code> pointer of a member function
1167 * that otherwise takes no arguments) to the <code>this</code> pointer of the
1168 * FEValues object. Note how here there is no need for the code that owns the
1169 * triangulation and the FEValues object to inform the latter if the former is
1170 * refined. (In practice, the function would want to connect to some of the
1171 * other signals that the triangulation offers as well, in particular to
1172 * creation and deletion signals.)
1173 *
1174 * The Triangulation class has a variety of signals that indicate different
1175 * actions by which the triangulation can modify itself and potentially
1176 * require follow-up action elsewhere. Please refer to Triangulation::Signals
1177 * for details.
1178 *
1179 * <h3>Serializing (loading or storing) triangulations</h3>
1180 *
1181 * Like many other classes in deal.II, the Triangulation class can stream its
1182 * contents to an archive using BOOST's serialization facilities. The data so
1183 * stored can later be retrieved again from the archive to restore the
1184 * contents of this object. This facility is frequently used to save the state
1185 * of a program to disk for possible later resurrection, often in the context
1186 * of checkpoint/restart strategies for long running computations or on
1187 * computers that aren't very reliable (e.g. on very large clusters where
1188 * individual nodes occasionally fail and then bring down an entire MPI job).
1189 *
1190 * For technical reasons, writing and restoring a Triangulation object is not
1191 * trivial. The primary reason is that unlike many other objects,
1192 * triangulations rely on many other objects to which they store pointers or
1193 * with which they interface; for example, triangulations store pointers to
1194 * objects describing boundaries and manifolds, and they have signals that
1195 * store pointers to other objects so they can be notified of changes in the
1196 * triangulation (see the section on signals in this introduction). Since these
1197 * objects are owned by the user space (for example the user can create a custom
1198 * manifold object), they may not be serializable. So in cases like this,
1199 * boost::serialize can store a reference to an object instead of the pointer,
1200 * but the reference will never be satisfied at write time because the object
1201 * pointed to is not serialized. Clearly, at load time, boost::serialize will
1202 * not know where to let the pointer point to because it never gets to re-create
1203 * the object originally pointed to.
1204 *
1205 * For these reasons, saving a triangulation to an archive does not store all
1206 * information, but only certain parts. More specifically, the information
1207 * that is stored is everything that defines the mesh such as vertex
1208 * locations, vertex indices, how vertices are connected to cells, boundary
1209 * indicators, subdomain ids, material ids, etc. On the other hand, the
1210 * following information is not stored:
1211 * - signals
1212 * - pointers to Manifold objects previously set using
1213 * Triangulation::set_manifold()
1214 *
1215 * On the other hand, since these are objects that
1216 * are usually set in user code, they can typically easily be set again in that
1217 * part of your code in which you re-load triangulations.
1218 *
1219 * In a sense, this approach to serialization means that re-loading a
1220 * triangulation is more akin to calling the
1221 * Triangulation::create_triangulation() function and filling it with some
1222 * additional content, as that function also does not touch the signals and
1223 * Manifold objects that belong to this triangulation. In keeping with this
1224 * analogy, the Triangulation::load() function also triggers the same kinds of
1225 * signal as Triangulation::create_triangulation().
1226 *
1227 *
1228 * <h3>Technical details</h3>
1229 *
1230 * <h4>%Algorithms for mesh regularization and smoothing upon refinement</h4>
1231 *
1232 * We chose an inductive point of view: since upon creation of the
1233 * triangulation all cells are on the same level, all regularity assumptions
1234 * regarding the maximum difference in level of cells sharing a common face,
1235 * edge or vertex hold. Since we use the regularization and smoothing in each
1236 * step of the mesh history, when coming to the point of refining it further
1237 * the assumptions also hold.
1238 *
1239 * The regularization and smoothing is done in the @p
1240 * prepare_coarsening_and_refinement function, which is called by @p
1241 * execute_coarsening_and_refinement at the very beginning. It decides which
1242 * additional cells to flag for refinement by looking at the old grid and the
1243 * refinement flags for each cell.
1244 *
1245 * <ul>
1246 * <li> <em>Regularization:</em> The algorithm walks over all cells checking
1247 * whether the present cell is flagged for refinement and a neighbor of the
1248 * present cell is refined once less than the present one. If so, flag the
1249 * neighbor for refinement. Because of the induction above, there may be no
1250 * neighbor with level two less than the present one.
1251 *
1252 * The neighbor thus flagged for refinement may induce more cells which need
1253 * to be refined. However, such cells which need additional refinement always
1254 * are on one level lower than the present one, so we can get away with only
1255 * one sweep over all cells if we do the loop in the reverse way, starting
1256 * with those on the highest level. This way, we may flag additional cells on
1257 * lower levels, but if these induce more refinement needed, this is performed
1258 * later on when we visit them in out backward running loop.
1259 *
1260 * <li> <em>Smoothing:</em>
1261 * <ul>
1262 * <li> @p limit_level_difference_at_vertices: First a list is set up which
1263 * stores for each vertex the highest level one of the adjacent cells belongs
1264 * to. Now, since we did smoothing in the previous refinement steps also, each
1265 * cell may only have vertices with levels at most one greater than the level
1266 * of the present cell.
1267 *
1268 * However, if we store the level plus one for cells marked for refinement, we
1269 * may end up with cells which have vertices of level two greater than the
1270 * cells level. We need to refine this cell also, and need thus also update
1271 * the levels of its vertices. This itself may lead to cells needing
1272 * refinement, but these are on lower levels, as above, which is why we may do
1273 * all kinds of additional flagging in one loop only.
1274 *
1275 * <li> @p eliminate_unrefined_islands: For each cell we count the number of
1276 * neighbors which are refined or flagged for refinement. If this exceeds the
1277 * number of neighbors which are not refined and not flagged for refinement,
1278 * then the current cell is flagged for refinement. Since this may lead to
1279 * cells on the same level which also will need refinement, we will need
1280 * additional loops of regularization and smoothing over all cells until
1281 * nothing changes any more.
1282 *
1283 * <li> <tt>eliminate_refined_*_islands</tt>: This one does much the same as
1284 * the above one, but for coarsening. If a cell is flagged for refinement or
1285 * if all of its children are active and if the number of neighbors which are
1286 * either active and not flagged for refinement, or not active but all
1287 * children flagged for coarsening equals the total number of neighbors, then
1288 * this cell's children are flagged for coarsening or (if this cell was
1289 * flagged for refinement) the refine flag is cleared.
1290 *
1291 * For a description of the distinction between the two versions of the flag
1292 * see above in the section about mesh smoothing in the general part of this
1293 * classes description.
1294 *
1295 * The same applies as above: several loops may be necessary.
1296 * </ul>
1297 * </ul>
1298 *
1299 * Regularization and smoothing are a bit complementary in that we check
1300 * whether we need to set additional refinement flags when being on a cell
1301 * flagged for refinement (regularization) or on a cell not flagged for
1302 * refinement. This makes readable programming easier.
1303 *
1304 * All the described algorithms apply only for more than one space dimension,
1305 * since for one dimension no restrictions apply. It may be necessary to apply
1306 * some smoothing for multigrid algorithms, but this has to be decided upon
1307 * later.
1308 *
1309 *
1310 * <h3>Warning</h3>
1311 *
1312 * It seems impossible to preserve @p constness of a triangulation through
1313 * iterator usage. Thus, if you declare pointers to a @p const triangulation
1314 * object, you should be well aware that you might involuntarily alter the
1315 * data stored in the triangulation.
1316 *
1317 * @ingroup grid
1318 *
1319 * @dealiiConceptRequires{(concepts::is_valid_dim_spacedim<dim, spacedim>)}
1320 */
1321 template <int dim, int spacedim = dim>
1322 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
1323 class Triangulation : public EnableObserverPointer
1324 {
1325 private:
1326 /**
1327 * An internal alias to make the definition of the iterator classes
1328 * simpler.
1329 */
1330 using IteratorSelector =
1331 dealii::internal::TriangulationImplementation::Iterators<dim, spacedim>;
1332
1333 public:
1334 /**
1335 * Declare some symbolic names for mesh smoothing algorithms. The meaning of
1336 * these flags is documented in the Triangulation class.
1337 */
1338 enum MeshSmoothing
1339 {
1340 /**
1341 * No mesh smoothing at all, except that meshes have to remain
1342 * one-irregular.
1343 */
1344 none = 0x0,
1345 /**
1346 * It can be shown, that degradation of approximation occurs if the
1347 * triangulation contains vertices which are member of cells with levels
1348 * differing by more than one. One such example is the following:
1349 *
1350 * @image html limit_level_difference_at_vertices.png ""
1351 *
1352 * It would seem that in two space dimensions, the maximum jump in levels
1353 * between cells sharing a common vertex is two (as in the example above).
1354 * However, this is not true if more than four cells meet at a vertex. It
1355 * is not uncommon that a
1356 * @ref GlossCoarseMesh "coarse (initial) mesh" contains vertices at which
1357 * six or even eight cells meet, when small features of the domain have to
1358 * be resolved even on the coarsest mesh. In that case, the maximum
1359 * difference in levels is three or four, respectively. The problem gets
1360 * even worse in three space dimensions.
1361 *
1362 * Looking at an interpolation of the second derivative of the finite
1363 * element solution (assuming bilinear finite elements), one sees that the
1364 * numerical solution is almost totally wrong, compared with the true
1365 * second derivative. Indeed, on regular meshes, there exist sharp
1366 * estimations that the H<sup>2</sup>-error is only of order one, so we
1367 * should not be surprised; however, the numerical solution may show a
1368 * value for the second derivative which may be a factor of ten away from
1369 * the true value. These problems are located on the small cell adjacent
1370 * to the center vertex, where cells of non-subsequent levels meet, as
1371 * well as on the upper and right neighbor of this cell (but with a less
1372 * degree of deviation from the true value).
1373 *
1374 * If the smoothing indicator given to the constructor contains the bit
1375 * for #limit_level_difference_at_vertices, situations as the above one
1376 * are eliminated by also marking the upper right cell for refinement.
1377 *
1378 * In case of anisotropic refinement, the level of a cell is not linked to
1379 * the refinement of a cell as directly as in case of isotropic
1380 * refinement. Furthermore, a cell can be strongly refined in one
1381 * direction and not or at least much less refined in another. Therefore,
1382 * it is very difficult to decide, which cases should be excluded from the
1383 * refinement process. As a consequence, when using anisotropic
1384 * refinement, the #limit_level_difference_at_vertices flag must not be
1385 * set. On the other hand, the implementation of multigrid methods in
1386 * deal.II requires that this bit be set.
1387 */
1388 limit_level_difference_at_vertices = 0x1,
1389 /**
1390 * Single cells which are not refined and are surrounded by cells which
1391 * are refined usually also lead to a sharp decline in approximation
1392 * properties locally. The reason is that the nodes on the faces between
1393 * unrefined and refined cells are not real degrees of freedom but carry
1394 * constraints. The patch without additional degrees of freedom is thus
1395 * significantly larger then the unrefined cell itself. If in the
1396 * parameter passed to the constructor the bit for
1397 * #eliminate_unrefined_islands is set, all cells which are not flagged
1398 * for refinement but which are surrounded by more refined cells than
1399 * unrefined cells are flagged for refinement. Cells which are not yet
1400 * refined but flagged for that are accounted for the number of refined
1401 * neighbors. Cells on the boundary are not accounted for at all. An
1402 * unrefined island is, by this definition also a cell which (in 2d) is
1403 * surrounded by three refined cells and one unrefined one, or one
1404 * surrounded by two refined cells, one unrefined one and is at the
1405 * boundary on one side. It is thus not a true island, as the name of the
1406 * flag may indicate. However, no better name came to mind to the author
1407 * by now.
1408 */
1409 eliminate_unrefined_islands = 0x2,
1410 /**
1411 * A triangulation of patch level 1 consists of patches, i.e. of cells
1412 * that are refined once. This flag ensures that a mesh of patch level 1
1413 * is still of patch level 1 after coarsening and refinement. It is,
1414 * however, the user's responsibility to ensure that the mesh is of patch
1415 * level 1 before calling
1416 * Triangulation::execute_coarsening_and_refinement() the first time. The
1417 * easiest way to achieve this is by calling global_refine(1) straight
1418 * after creation of the triangulation. It follows that if at least one
1419 * of the children of a cell is or will be refined than all children need
1420 * to be refined. If the #patch_level_1 flag is set, than the flags
1421 * #eliminate_unrefined_islands, #eliminate_refined_inner_islands and
1422 * #eliminate_refined_boundary_islands will be ignored as they will be
1423 * fulfilled automatically.
1424 */
1425 patch_level_1 = 0x4,
1426 /**
1427 * Each
1428 * @ref GlossCoarseMesh "coarse grid"
1429 * cell is refined at least once,
1430 * i.e., the triangulation
1431 * might have active cells on level 1 but not on level 0. This flag
1432 * ensures that a mesh which has coarsest_level_1 has still
1433 * coarsest_level_1 after coarsening and refinement. It is, however, the
1434 * user's responsibility to ensure that the mesh has coarsest_level_1
1435 * before calling execute_coarsening_and_refinement the first time. The
1436 * easiest way to achieve this is by calling global_refine(1) straight
1437 * after creation of the triangulation. It follows that active cells on
1438 * level 1 may not be coarsened.
1439 *
1440 * The main use of this flag is to ensure that each cell has at least one
1441 * neighbor in each coordinate direction (i.e. each cell has at least a
1442 * left or right, and at least an upper or lower neighbor in 2d). This is
1443 * a necessary precondition for some algorithms that compute finite
1444 * differences between cells. The DerivativeApproximation class is one of
1445 * these algorithms that require that a triangulation is coarsest_level_1
1446 * unless all cells already have at least one neighbor in each coordinate
1447 * direction on the coarsest level.
1448 */
1449 coarsest_level_1 = 0x8,
1450 /**
1451 * This flag is not included in @p maximum_smoothing. The flag is
1452 * concerned with the following case: consider the case that an unrefined
1453 * and a refined cell share a common face and that one of the children of
1454 * the refined cell along the common face is flagged for further
1455 * refinement. In that case, the resulting mesh would have more than one
1456 * hanging node along one or more of the edges of the triangulation, a
1457 * situation that is not allowed. Consequently, in order to perform the
1458 * refinement, the coarser of the two original cells is also going to be
1459 * refined.
1460 *
1461 * However, in many cases it is sufficient to refine the coarser of the
1462 * two original cells in an anisotropic way to avoid the case of multiple
1463 * hanging vertices on a single edge. Doing only the minimal anisotropic
1464 * refinement can save cells and degrees of freedom. By specifying this
1465 * flag, the library can produce these anisotropic refinements.
1466 *
1467 * The flag is not included by default since it may lead to
1468 * anisotropically refined meshes even though no cell has ever been
1469 * refined anisotropically explicitly by a user command. This surprising
1470 * fact may lead to programs that do the wrong thing since they are not
1471 * written for the additional cases that can happen with anisotropic
1472 * meshes, see the discussion in the introduction to step-30.
1473 */
1474 allow_anisotropic_smoothing = 0x10,
1475 /**
1476 * This algorithm seeks for isolated cells which are refined or flagged
1477 * for refinement. This definition is unlike that for
1478 * #eliminate_unrefined_islands, which would mean that an island is
1479 * defined as a cell which is refined but more of its neighbors are not
1480 * refined than are refined. For example, in 2d, a cell's refinement would
1481 * be reverted if at most one of its neighbors is also refined (or refined
1482 * but flagged for coarsening).
1483 *
1484 * The reason for the change in definition of an island is, that this
1485 * option would be a bit dangerous, since if you consider a chain of
1486 * refined cells (e.g. along a kink in the solution), the cells at the two
1487 * ends would be coarsened, after which the next outermost cells would
1488 * need to be coarsened. Therefore, only one loop of flagging cells like
1489 * this could be done to avoid eating up the whole chain of refined cells
1490 * (`chain reaction'...).
1491 *
1492 * This algorithm also takes into account cells which are not actually
1493 * refined but are flagged for refinement. If necessary, it takes away the
1494 * refinement flag.
1495 *
1496 * Actually there are two versions of this flag,
1497 * #eliminate_refined_inner_islands and
1498 * #eliminate_refined_boundary_islands. The first eliminates islands
1499 * defined by the definition above which are in the interior of the
1500 * domain, while the second eliminates only those islands if the cell is
1501 * at the boundary. The reason for this split of flags is that one often
1502 * wants to eliminate such islands in the interior while those at the
1503 * boundary may well be wanted, for example if one refines the mesh
1504 * according to a criterion associated with a boundary integral or if one
1505 * has rough boundary data.
1506 */
1507 eliminate_refined_inner_islands = 0x100,
1508 /**
1509 * The result of this flag is very similar to
1510 * #eliminate_refined_inner_islands. See the documentation there.
1511 */
1512 eliminate_refined_boundary_islands = 0x200,
1513 /**
1514 * This flag prevents the occurrence of unrefined islands. In more detail:
1515 * It prohibits the coarsening of a cell if 'most of the neighbors' will
1516 * be refined after the step.
1517 */
1518 do_not_produce_unrefined_islands = 0x400,
1519
1520 /**
1521 * This flag sums up all smoothing algorithms which may be performed upon
1522 * refinement by flagging some more cells for refinement.
1523 */
1524 smoothing_on_refinement =
1525 (limit_level_difference_at_vertices | eliminate_unrefined_islands),
1526 /**
1527 * This flag sums up all smoothing algorithms which may be performed upon
1528 * coarsening by flagging some more cells for coarsening.
1529 */
1530 smoothing_on_coarsening =
1531 (eliminate_refined_inner_islands | eliminate_refined_boundary_islands |
1532 do_not_produce_unrefined_islands),
1533
1534 /**
1535 * This flag includes all the above ones (therefore combines all
1536 * smoothing algorithms implemented), with the exception of anisotropic
1537 * smoothing.
1538 */
1539 maximum_smoothing = 0xffff ^ allow_anisotropic_smoothing
1540 };
1541
1542 /**
1543 * An alias that is used to identify cell iterators. The concept of
1544 * iterators is discussed at length in the
1545 * @ref Iterators "iterators documentation topic".
1546 *
1547 * The current alias identifies cells in a triangulation. The TriaIterator
1548 * class works like a pointer that when you dereference it yields an object
1549 * of type CellAccessor. CellAccessor is a class that identifies properties
1550 * that are specific to cells in a triangulation, but it is derived (and
1551 * consequently inherits) from TriaAccessor that describes what you can ask
1552 * of more general objects (lines, faces, as well as cells) in a
1553 * triangulation.
1554 *
1555 * @ingroup Iterators
1556 */
1557 using cell_iterator = TriaIterator<CellAccessor<dim, spacedim>>;
1558
1559 /**
1560 * The same as above to allow the usage of the "MeshType concept" also
1561 * on the refinement levels.
1562 */
1563 using level_cell_iterator = cell_iterator;
1564
1565 /**
1566 * An alias that is used to identify
1567 * @ref GlossActive "active cell iterators".
1568 * The concept of iterators is discussed at length in the
1569 * @ref Iterators "iterators documentation topic".
1570 *
1571 * The current alias identifies active cells in a triangulation. The
1572 * TriaActiveIterator class works like a pointer to active objects that when
1573 * you dereference it yields an object of type CellAccessor. CellAccessor is
1574 * a class that identifies properties that are specific to cells in a
1575 * triangulation, but it is derived (and consequently inherits) from
1576 * TriaAccessor that describes what you can ask of more general objects
1577 * (lines, faces, as well as cells) in a triangulation.
1578 *
1579 * @ingroup Iterators
1580 */
1581 using active_cell_iterator = TriaActiveIterator<CellAccessor<dim, spacedim>>;
1582
1583 /**
1584 * An alias that is used to identify iterators that point to faces.
1585 * The concept of iterators is discussed at length in the
1586 * @ref Iterators "iterators documentation topic".
1587 *
1588 * The current alias identifies faces in a triangulation. The
1589 * TriaIterator class works like a pointer to objects that when
1590 * you dereference it yields an object of type TriaAccessor, i.e.,
1591 * class that can be used to query geometric properties of faces
1592 * such as their vertices, their area, etc.
1593 *
1594 * @ingroup Iterators
1595 */
1596 using face_iterator = TriaIterator<TriaAccessor<dim - 1, dim, spacedim>>;
1597
1598 /**
1599 * An alias that is used to identify iterators that point to active faces,
1600 * i.e., to faces that have no children. Active faces must be faces of at
1601 * least one active cell.
1602 *
1603 * Other than the "active" qualification, this alias is identical to the
1604 * @p face_iterator alias. In particular, dereferencing either yields
1605 * the same kind of object.
1606 *
1607 * @ingroup Iterators
1608 */
1609 using active_face_iterator =
1610 TriaActiveIterator<TriaAccessor<dim - 1, dim, spacedim>>;
1611
1612 /**
1613 * An alias that defines an iterator type to iterate over
1614 * vertices of a mesh. The concept of iterators is discussed at
1615 * length in the
1616 * @ref Iterators "iterators documentation topic".
1617 *
1618 * @ingroup Iterators
1619 */
1620 using vertex_iterator = TriaIterator<dealii::TriaAccessor<0, dim, spacedim>>;
1621
1622 /**
1623 * An alias that defines an iterator type to iterate over
1624 * vertices of a mesh. The concept of iterators is discussed at
1625 * length in the
1626 * @ref Iterators "iterators documentation topic".
1627 *
1628 * This alias is in fact identical to the @p vertex_iterator alias
1629 * above since all vertices in a mesh are active (i.e., are a vertex of
1630 * an active cell).
1631 *
1632 * @ingroup Iterators
1633 */
1634 using active_vertex_iterator =
1635 TriaActiveIterator<dealii::TriaAccessor<0, dim, spacedim>>;
1636
1637 /**
1638 * An alias that defines an iterator over the (one-dimensional) lines
1639 * of a mesh. In one-dimensional meshes, these are the cells of the mesh,
1640 * whereas in two-dimensional meshes the lines are the faces of cells.
1641 *
1642 * @ingroup Iterators
1643 */
1644 using line_iterator = typename IteratorSelector::line_iterator;
1645
1646 /**
1647 * An alias that allows iterating over the <i>active</i> lines, i.e.,
1648 * that subset of lines that have no children. In one-dimensional meshes,
1649 * these are the cells of the mesh, whereas in two-dimensional
1650 * meshes the lines are the faces of cells.
1651 *
1652 * In two- or three-dimensional meshes, lines without children (i.e.,
1653 * the active lines) are part of at least one active cell. Each such line may
1654 * additionally be a child of a line of a coarser cell adjacent to a cell
1655 * that is active. (This coarser neighbor would then also be active.)
1656 *
1657 * @ingroup Iterators
1658 */
1659 using active_line_iterator = typename IteratorSelector::active_line_iterator;
1660
1661 /**
1662 * An alias that defines an iterator over the (two-dimensional) quads
1663 * of a mesh. In two-dimensional meshes, these are the cells of the mesh,
1664 * whereas in three-dimensional meshes the quads are the faces of cells.
1665 *
1666 * @ingroup Iterators
1667 */
1668 using quad_iterator = typename IteratorSelector::quad_iterator;
1669
1670 /**
1671 * An alias that allows iterating over the <i>active</i> quads, i.e.,
1672 * that subset of quads that have no children. In two-dimensional meshes,
1673 * these are the cells of the mesh, whereas in three-dimensional
1674 * meshes the quads are the faces of cells.
1675 *
1676 * In three-dimensional meshes, quads without children (i.e.,
1677 * the active quads) are faces of at least one active cell. Each such quad may
1678 * additionally be a child of a quad face of a coarser cell adjacent to a cell
1679 * that is active. (This coarser neighbor would then also be active.)
1680 *
1681 * @ingroup Iterators
1682 */
1683 using active_quad_iterator = typename IteratorSelector::active_quad_iterator;
1684
1685 /**
1686 * An alias that defines an iterator over the (three-dimensional) hexes
1687 * of a mesh. This iterator only makes sense in three-dimensional meshes,
1688 * where hexes are the cells of the mesh.
1689 *
1690 * @ingroup Iterators
1691 */
1692 using hex_iterator = typename IteratorSelector::hex_iterator;
1693
1694 /**
1695 * An alias that allows iterating over the <i>active</i> hexes of a mesh.
1696 * This iterator only makes sense in three-dimensional meshes,
1697 * where hexes are the cells of the mesh. Consequently, in these
1698 * three-dimensional meshes, this iterator is equivalent to the
1699 * @p active_cell_iterator alias.
1700 *
1701 * @ingroup Iterators
1702 */
1703 using active_hex_iterator = typename IteratorSelector::active_hex_iterator;
1704
1705 /**
1706 * A structure that is used as an exception object by the
1707 * create_triangulation() function to indicate which cells among the coarse
1708 * mesh cells are inverted or severely distorted (see the entry on
1709 * @ref GlossDistorted "distorted cells"
1710 * in the glossary).
1711 *
1712 * Objects of this kind are thrown by the create_triangulation() and
1713 * execute_coarsening_and_refinement() functions, and they can be caught in
1714 * user code if this condition is to be ignored. Note, however, that such
1715 * exceptions are only produced if the necessity for this check was
1716 * indicated when calling the constructor of the Triangulation class.
1717 *
1718 * A cell is called <i>deformed</i> if the determinant of the Jacobian of
1719 * the mapping from reference cell to real cell is negative at least at one
1720 * vertex. This computation is done using the
1721 * GeometryInfo::jacobian_determinants_at_vertices function.
1722 */
1723 struct DistortedCellList : public dealii::ExceptionBase
1724 {
1725 /**
1726 * Destructor. Empty, but needed for the sake of exception specification,
1727 * since the base class has this exception specification and the
1728 * automatically generated destructor would have a different one due to
1729 * member objects.
1730 */
1731 virtual ~DistortedCellList() noexcept override;
1732
1733 /**
1734 * A list of those cells among the coarse mesh cells that are deformed or
1735 * whose children are deformed.
1736 */
1737 std::list<typename Triangulation<dim, spacedim>::cell_iterator>
1738 distorted_cells;
1739 };
1740
1741 /**
1742 * Make the dimension available in function templates.
1743 */
1744 static constexpr unsigned int dimension = dim;
1745
1746 /**
1747 * Make the space-dimension available in function templates.
1748 */
1749 static constexpr unsigned int space_dimension = spacedim;
1750
1751 /**
1752 * Create an empty triangulation. Do not create any cells.
1753 *
1754 * @param smooth_grid Determines the level of smoothness of the mesh size
1755 * function that should be enforced upon mesh refinement.
1756 *
1757 * @param check_for_distorted_cells Determines whether the triangulation
1758 * should check whether any of the cells that are created by
1759 * create_triangulation() or execute_coarsening_and_refinement() are
1760 * distorted (see
1761 * @ref GlossDistorted "distorted cells").
1762 * If set, these two functions may throw an exception if they encounter
1763 * distorted cells.
1764 */
1765 Triangulation(const MeshSmoothing smooth_grid = none,
1766 const bool check_for_distorted_cells = false);
1767
1768 /**
1769 * Copy constructor.
1770 *
1771 * You should really use the @p copy_triangulation function, so this
1772 * constructor is deleted. The reason for this is
1773 * that we may want to use triangulation objects in collections. However,
1774 * C++ containers require that the objects stored in them are copyable, so
1775 * we need to provide a copy constructor. On the other hand, copying
1776 * triangulations is so expensive that we do not want such objects copied by
1777 * accident, for example in compiler-generated temporary objects. By
1778 * defining a copy constructor but throwing an error, we satisfy the formal
1779 * requirements of containers, but at the same time disallow actual copies.
1780 * Finally, through the exception, one easily finds the places where code
1781 * has to be changed to avoid copies.
1782 */
1783 Triangulation(const Triangulation<dim, spacedim> &) = delete;
1784
1785 /**
1786 * Move constructor.
1787 *
1788 * Create a new triangulation by stealing the internal data of another
1789 * triangulation.
1790 */
1791 Triangulation(Triangulation<dim, spacedim> &&tria) noexcept;
1792
1793 /**
1794 * Move assignment operator.
1795 */
1796 Triangulation &
1797 operator=(Triangulation<dim, spacedim> &&tria) noexcept;
1798
1799 /**
1800 * Delete the object and all levels of the hierarchy.
1801 */
1802 virtual ~Triangulation() override;
1803
1804 /**
1805 * Reset this triangulation into an empty state by deleting all data.
1806 *
1807 * Note that this operation is only allowed if no subscriptions to this
1808 * object exist any more, such as DoFHandler objects using it.
1809 */
1810 virtual void
1811 clear();
1812
1813 /**
1814 * Return the MPI communicator used by this triangulation. In the case of a
1815 * serial Triangulation object, MPI_COMM_SELF is returned.
1816 */
1817 virtual MPI_Comm
1818 get_mpi_communicator() const;
1819
1820 /**
1821 * Return the MPI communicator used by this triangulation. In the case of
1822 * a serial Triangulation object, MPI_COMM_SELF is returned.
1823 *
1824 * @deprecated Use get_mpi_communicator() instead.
1825 */
1826 DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
1827 "Access the MPI communicator with get_mpi_communicator() instead.")
1828 MPI_Comm
1829 get_communicator() const;
1830
1831 /**
1832 * Return the partitioner for the global indices of the cells on the active
1833 * level of the triangulation, which is returned by the function
1834 * CellAccessor::global_active_cell_index().
1835 */
1836 virtual std::weak_ptr<const Utilities::MPI::Partitioner>
1837 global_active_cell_index_partitioner() const;
1838
1839 /**
1840 * Return the partitioner for the global indices of the cells on the given @p
1841 * level of the triangulation, which is returned by the function
1842 * CellAccessor::global_level_cell_index().
1843 */
1844 virtual std::weak_ptr<const Utilities::MPI::Partitioner>
1845 global_level_cell_index_partitioner(const unsigned int level) const;
1846
1847 /**
1848 * Set the mesh smoothing to @p mesh_smoothing. This overrides the
1849 * MeshSmoothing given to the constructor.
1850 */
1851 virtual void
1852 set_mesh_smoothing(const MeshSmoothing mesh_smoothing);
1853
1854 /**
1855 * Return the mesh smoothing requirements that are obeyed.
1856 */
1857 virtual const MeshSmoothing &
1858 get_mesh_smoothing() const;
1859
1860 /**
1861 * Assign a manifold object to a certain part of the triangulation. If
1862 * an object with manifold number @p number is refined, this object is used
1863 * to find the location of new vertices (see the results section of step-49
1864 * for a more in-depth discussion of this, with examples). It is also used
1865 * for non-linear (i.e.: non-Q1) transformations of cells to the unit cell
1866 * in shape function calculations.
1867 *
1868 * A copy of @p manifold_object is created using
1869 * Manifold<dim, spacedim>::clone() and stored internally.
1870 *
1871 * It is possible to remove or replace a Manifold object during the
1872 * lifetime of a non-empty triangulation. Usually, this is done before the
1873 * first refinement and is dangerous afterwards. Removal of a manifold
1874 * object is done by reset_manifold(). This operation then replaces the
1875 * manifold object given before by a straight manifold approximation.
1876 *
1877 * @ingroup manifold
1878 *
1879 * @see
1880 * @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
1881 */
1882 void
1883 set_manifold(const types::manifold_id number,
1884 const Manifold<dim, spacedim> &manifold_object);
1885
1886 /**
1887 * Reset those parts of the triangulation with the given
1888 * @p manifold_number to use a FlatManifold object. This is the
1889 * default state of a non-curved triangulation, and undoes
1890 * assignment of a different Manifold object by the function
1891 * Triangulation::set_manifold().
1892 *
1893 * @note Geometric objects with the manifold ID @p manifold_number will
1894 * still have the same ID after calling this function so that the function
1895 * get_manifold_ids() will still return the same set of IDs.
1896 *
1897 * @ingroup manifold
1898 *
1899 * @see
1900 * @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
1901 */
1902 void
1903 reset_manifold(const types::manifold_id manifold_number);
1904
1905 /**
1906 * Reset all parts of the triangulation, regardless of their
1907 * manifold_id, to use a FlatManifold object. This undoes assignment
1908 * of all Manifold objects by the function
1909 * Triangulation::set_manifold().
1910 *
1911 * @note Geometric objects not having numbers::flat_manifold_id as manifold ID
1912 * will after calling this function still have the same IDs. Their IDs are
1913 * not replaced by numbers::flat_manifold_id so that the function
1914 * get_manifold_ids() will still return the same set of IDs.
1915 *
1916 * @ingroup manifold
1917 *
1918 * @see
1919 * @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
1920 */
1921 void
1922 reset_all_manifolds();
1923
1924 /**
1925 * Set the manifold_id of all cells and faces to the given argument.
1926 *
1927 * @ingroup manifold
1928 *
1929 * @see
1930 * @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
1931 */
1932 void
1933 set_all_manifold_ids(const types::manifold_id number);
1934
1935 /**
1936 * Set the manifold_id of all boundary faces to the given argument.
1937 *
1938 * @ingroup manifold
1939 *
1940 * @see
1941 * @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
1942 */
1943 void
1944 set_all_manifold_ids_on_boundary(const types::manifold_id number);
1945
1946 /**
1947 * Set the manifold_id of all boundary faces and edges with given
1948 * boundary_id @p b_id to the given manifold_id @p number.
1949 *
1950 * @ingroup manifold
1951 *
1952 * @see
1953 * @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
1954 */
1955 void
1956 set_all_manifold_ids_on_boundary(const types::boundary_id b_id,
1957 const types::manifold_id number);
1958
1959 /**
1960 * Return a constant reference to a Manifold object used for this
1961 * triangulation. @p number is the same as in set_manifold().
1962 *
1963 * @note In debug mode, this function checks that @p number has been
1964 * previously associated with a Manifold via set_manifold(). If it has not
1965 * then an assertion is triggered.
1966 *
1967 * @ingroup manifold
1968 *
1969 * @see
1970 * @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
1971 */
1972 const Manifold<dim, spacedim> &
1973 get_manifold(const types::manifold_id number) const;
1974
1975 /**
1976 * Return a vector containing all boundary indicators assigned to boundary
1977 * faces of active cells of this Triangulation object. Note, that each
1978 * boundary indicator is reported only once. The size of the return vector
1979 * will represent the number of different indicators (which is greater or
1980 * equal one).
1981 *
1982 * @see
1983 * @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
1984 */
1985 virtual std::vector<types::boundary_id>
1986 get_boundary_ids() const;
1987
1988 /**
1989 * Return a vector containing all manifold indicators assigned to the
1990 * objects of the active cells of this Triangulation. Note, that each
1991 * manifold indicator is reported only once. The size of the return vector
1992 * will represent the number of different indicators (which is greater or
1993 * equal one).
1994 *
1995 * @ingroup manifold
1996 *
1997 * @see
1998 * @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
1999 */
2000 virtual std::vector<types::manifold_id>
2001 get_manifold_ids() const;
2002
2003 /**
2004 * Copy @p other_tria to this triangulation. This operation is not cheap, so
2005 * you should be careful with using this. We do not implement this function
2006 * as a copy constructor, since it makes it easier to maintain collections
2007 * of triangulations if you can assign them values later on.
2008 *
2009 * This triangulation must be empty beforehand.
2010 *
2011 * The function is made @p virtual since some derived classes might want to
2012 * disable or extend the functionality of this function.
2013 *
2014 * @note Calling this function triggers the 'copy' signal on other_tria, i.e.
2015 * the triangulation being copied <i>from</i>. It also triggers the
2016 * 'create' signal of the current triangulation. See the section on signals
2017 * in the general documentation for more information.
2018 *
2019 * @note The list of connections to signals is not copied from the old to
2020 * the new triangulation since these connections were established to monitor
2021 * how the old triangulation changes, not how any triangulation it may be
2022 * copied to changes.
2023 */
2024 virtual void
2025 copy_triangulation(const Triangulation<dim, spacedim> &other_tria);
2026
2027 /**
2028 * Create a triangulation from a list of vertices and a list of cells, each
2029 * of the latter being a list of <tt>1<<dim</tt> vertex indices. The
2030 * triangulation must be empty upon calling this function and the cell list
2031 * should be useful (connected domain, etc.). The result of calling this
2032 * function is a
2033 * @ref GlossCoarseMesh "coarse mesh".
2034 *
2035 * Material data for the cells is given within the @p cells array, while
2036 * boundary information is given in the @p subcelldata field.
2037 *
2038 * The numbering of vertices within the @p cells array is subject to some
2039 * constraints; see the general class documentation for this.
2040 *
2041 * For conditions when this function can generate a valid triangulation, see
2042 * the documentation of this class, and the GridIn and
2043 * GridTools::consistently_order_cells() function.
2044 *
2045 * If the <code>check_for_distorted_cells</code> flag was specified upon
2046 * creation of this object, at the very end of its operation, the current
2047 * function walks over all cells and verifies that none of the cells is
2048 * deformed (see the entry on
2049 * @ref GlossDistorted "distorted cells"
2050 * in the glossary), where we call a cell deformed if the determinant of the
2051 * Jacobian of the mapping from reference cell to real cell is negative at
2052 * least at one of the vertices (this computation is done using the
2053 * GeometryInfo::jacobian_determinants_at_vertices function). If there are
2054 * deformed cells, this function throws an exception of kind
2055 * DistortedCellList. Since this happens after all data structures have been
2056 * set up, you can catch and ignore this exception if you know what you do
2057 * -- for example, it may be that the determinant is zero (indicating that
2058 * you have collapsed edges in a cell) but that this is ok because you
2059 * didn't intend to integrate on this cell anyway. On the other hand,
2060 * deformed cells are often a sign of a mesh that is too coarse to resolve
2061 * the geometry of the domain, and in this case ignoring the exception is
2062 * probably unwise.
2063 *
2064 * @note This function is used in step-14 and step-19.
2065 *
2066 * @note This function triggers the "create" signal after doing its work. See
2067 * the section on signals in the general documentation of this class. For
2068 * example as a consequence of this, all DoFHandler objects connected to
2069 * this triangulation will be reinitialized via DoFHandler::reinit().
2070 *
2071 * @note The check for distorted cells is only done if dim==spacedim, as
2072 * otherwise cells can legitimately be twisted if the manifold they describe
2073 * is twisted.
2074 */
2075 virtual void
2076 create_triangulation(const std::vector<Point<spacedim>> &vertices,
2077 const std::vector<CellData<dim>> &cells,
2078 const SubCellData &subcelldata);
2079
2080 /**
2081 * Create a triangulation from the provided
2082 * TriangulationDescription::Description.
2083 *
2084 * @note Don't forget to attach the manifolds with set_manifold() before
2085 * calling this function if manifolds are needed.
2086 *
2087 * @note The namespace TriangulationDescription::Utilities contains functions
2088 * to create TriangulationDescription::Description.
2089 *
2090 * @param construction_data The data needed for this process.
2091 */
2092 virtual void
2093 create_triangulation(
2094 const TriangulationDescription::Description<dim, spacedim>
2095 &construction_data);
2096
2097 /**
2098 * Revert or flip the direction flags of a triangulation with
2099 * `dim==spacedim-1`, see
2100 * @ref GlossDirectionFlag.
2101 *
2102 * This function throws an exception if `dim==spacedim` or if
2103 * `dim<spacedim-1`.
2104 */
2105 void
2106 flip_all_direction_flags();
2107
2108 /**
2109 * @name Mesh refinement
2110 * @{
2111 */
2112
2113 /**
2114 * Flag all active cells for refinement. This will refine all cells of all
2115 * levels which are not already refined (i.e. only cells are refined which
2116 * do not yet have children). The cells are only flagged, not refined, thus
2117 * you have the chance to save the refinement flags.
2118 */
2119 void
2120 set_all_refine_flags();
2121
2122 /**
2123 * Refine all cells @p times times. In other words, in each one of
2124 * the @p times iterations, loop over all cells and refine each cell
2125 * uniformly into $2^\text{dim}$ children. In practice, this
2126 * function repeats the following operations @p times times: call
2127 * set_all_refine_flags() followed by
2128 * execute_coarsening_and_refinement(). The end result is that the
2129 * number of cells increases by a factor of
2130 * $(2^\text{dim})^\text{times}=2^{\text{dim} \times \text{times}}$.
2131 *
2132 * The execute_coarsening_and_refinement() function called in this
2133 * loop may throw an exception if it creates cells that are
2134 * distorted (see its documentation for an explanation). This
2135 * exception will be propagated through this function if that
2136 * happens, and you may not get the actual number of refinement
2137 * steps in that case.
2138 *
2139 * @note This function triggers the pre- and post-refinement signals before
2140 * and after doing each individual refinement cycle (i.e. more than once if
2141 * `times > 1`) . See the section on signals in the general documentation of
2142 * this class.
2143 */
2144 void
2145 refine_global(const unsigned int times = 1);
2146
2147 /**
2148 * Coarsen all cells the given number of times.
2149 *
2150 * In each of one of the @p times iterations, all cells will be marked for
2151 * coarsening. If an active cell is already on the coarsest level, it will
2152 * be ignored.
2153 *
2154 * @note This function triggers the pre- and post-refinement signals before
2155 * and after doing each individual coarsening cycle (i.e. more than once if
2156 * `times > 1`) . See the section on signals in the general documentation of
2157 * this class.
2158 */
2159 void
2160 coarsen_global(const unsigned int times = 1);
2161
2162 /**
2163 * Execute both refinement and coarsening of the triangulation.
2164 *
2165 * The function resets all refinement and coarsening flags to false. It uses
2166 * the user flags for internal purposes. They will therefore be overwritten
2167 * by undefined content.
2168 *
2169 * To allow user programs to fix up these cells if that is desired, this
2170 * function after completing all other work may throw an exception of type
2171 * DistortedCellList that contains a list of those cells that have been
2172 * refined and have at least one child that is distorted. The function does
2173 * not create such an exception if no cells have created distorted children.
2174 * Note that for the check for distorted cells to happen, the
2175 * <code>check_for_distorted_cells</code> flag has to be specified upon
2176 * creation of a triangulation object.
2177 *
2178 * See the general docs for more information.
2179 *
2180 * @note This function triggers the pre- and post-refinement signals before
2181 * and after doing its work. See the section on signals in the general
2182 * documentation of this class.
2183 *
2184 * @note If the boundary description is sufficiently irregular, it can
2185 * happen that some of the children produced by mesh refinement are
2186 * distorted (see the extensive discussion on
2187 * @ref GlossDistorted "distorted cells").
2188 *
2189 * @note This function is <tt>virtual</tt> to allow derived classes to
2190 * insert hooks, such as saving refinement flags and the like (see e.g. the
2191 * PersistentTriangulation class).
2192 */
2193 virtual void
2194 execute_coarsening_and_refinement();
2195
2196 /**
2197 * Do both preparation for refinement and coarsening as well as mesh
2198 * smoothing.
2199 *
2200 * Regarding the refinement process it fixes the closure of the refinement
2201 * in <tt>dim>=2</tt> (make sure that no two cells are adjacent with a
2202 * refinement level differing with more than one), etc. It performs some
2203 * mesh smoothing if the according flag was given to the constructor of this
2204 * class. The function returns whether additional cells have been flagged
2205 * for refinement.
2206 *
2207 * See the general doc of this class for more information on smoothing upon
2208 * refinement.
2209 *
2210 * Regarding the coarsening part, flagging and deflagging cells in
2211 * preparation of the actual coarsening step are done. This includes
2212 * deleting coarsen flags from cells which may not be deleted (e.g. because
2213 * one neighbor is more refined than the cell), doing some smoothing, etc.
2214 *
2215 * The effect is that only those cells are flagged for coarsening which will
2216 * actually be coarsened. This includes the fact that all flagged cells
2217 * belong to parent cells of which all children are flagged.
2218 *
2219 * The function returns whether some cells' flagging has been changed in the
2220 * process.
2221 *
2222 * This function uses the user flags, so store them if you still need them
2223 * afterwards.
2224 */
2225 virtual bool
2226 prepare_coarsening_and_refinement();
2227
2228 /** @} */
2229
2230 /**
2231 * The elements of this `enum` are used to inform functions how a
2232 * specific cell is going to change. This is used in the course of
2233 * transferring data from one mesh to a refined or coarsened version of
2234 * the mesh, for example. Note that this may me different than the
2235 * refine_flag() and coarsen_flag() set on a cell, for example in
2236 * parallel calculations, because of refinement constraints that an
2237 * individual machine does not see.
2238 *
2239 * @deprecated This is an alias for backward compatibility. Use
2240 * ::dealii::CellStatus directly.
2241 */
2242 using CellStatus DEAL_II_DEPRECATED = ::dealii::CellStatus;
2243
2244 /**
2245 * @deprecated This is an alias for backward compatibility. Use
2246 * ::dealii::CellStatus directly.
2247 */
2248 static constexpr auto CELL_PERSIST DEAL_II_DEPRECATED =
2249 ::dealii::CellStatus::cell_will_persist;
2250
2251 /**
2252 * @deprecated This is an alias for backward compatibility. Use
2253 * ::dealii::CellStatus directly.
2254 */
2255 static constexpr auto CELL_REFINE DEAL_II_DEPRECATED =
2256 ::dealii::CellStatus::cell_will_be_refined;
2257
2258 /**
2259 * @deprecated This is an alias for backward compatibility. Use
2260 * ::dealii::CellStatus directly.
2261 */
2262 static constexpr auto CELL_COARSEN DEAL_II_DEPRECATED =
2263 ::dealii::CellStatus::children_will_be_coarsened;
2264
2265 /**
2266 * @deprecated This is an alias for backward compatibility. Use
2267 * ::dealii::CellStatus directly.
2268 */
2269 static constexpr auto CELL_INVALID DEAL_II_DEPRECATED =
2270 ::dealii::CellStatus::cell_invalid;
2271
2272
2273 /**
2274 * A structure used to accumulate the results of the `weight` signal slot
2275 * functions below. It takes an iterator range and returns the sum of
2276 * values.
2277 */
2278 template <typename T>
2279 struct CellWeightSum
2280 {
2281 using result_type = T;
2282
2283 template <typename InputIterator>
2284 T
2285 operator()(InputIterator first, InputIterator last) const
2286 {
2287 return std::accumulate(first, last, T());
2288 }
2289 };
2290
2291 /**
2292 * A structure that has boost::signal objects for a number of actions that a
2293 * triangulation can do to itself. Please refer to the "Getting notice when
2294 * a triangulation changes" section in the general documentation of the
2295 * Triangulation class for more information and examples.
2296 *
2297 * For documentation on signals, see
2298 * http://www.boost.org/doc/libs/release/libs/signals2 .
2299 */
2300 struct Signals
2301 {
2302 /**
2303 * This signal is triggered whenever the
2304 * Triangulation::create_triangulation or
2305 * Triangulation::copy_triangulation() is called. This signal is also
2306 * triggered when loading a triangulation from an archive via
2307 * Triangulation::load().
2308 */
2309 boost::signals2::signal<void()> create;
2310
2311 /**
2312 * This signal is triggered at the beginning of execution of the
2313 * Triangulation::execute_coarsening_and_refinement() function (which is
2314 * itself called by other functions such as Triangulation::refine_global()
2315 * ). At the time this signal is triggered, the triangulation is still
2316 * unchanged.
2317 */
2318 boost::signals2::signal<void()> pre_refinement;
2319
2320 /**
2321 * This signal is triggered at the end of execution of the
2322 * Triangulation::execute_coarsening_and_refinement() function when the
2323 * triangulation has reached its final state.
2324 */
2325 boost::signals2::signal<void()> post_refinement;
2326
2327 /**
2328 * This signal is triggered at the beginning of execution of the
2329 * GridTools::partition_triangulation() and
2330 * GridTools::partition_triangulation_zorder() functions. At the time this
2331 * signal is triggered, the triangulation is still unchanged.
2332 */
2333 boost::signals2::signal<void()> pre_partition;
2334
2335 /**
2336 * This signal is triggered when a function in deal.II moves the grid
2337 * points of a mesh, e.g. GridTools::transform. Unfortunately,
2338 * modification of a vertex in user code through
2339 * <code>cell_iterator->vertex(v) = xxxx</code> cannot be detected by this
2340 * method.
2341 */
2342 boost::signals2::signal<void()> mesh_movement;
2343
2344 /**
2345 * This signal is triggered for each cell that is going to be coarsened.
2346 *
2347 * @note This signal is triggered with the immediate parent cell of a set
2348 * of active cells as argument. The children of this parent cell will
2349 * subsequently be coarsened away.
2350 */
2351 boost::signals2::signal<void(
2352 const typename Triangulation<dim, spacedim>::cell_iterator &cell)>
2353 pre_coarsening_on_cell;
2354
2355 /**
2356 * This signal is triggered for each cell that just has been refined.
2357 *
2358 * @note The signal parameter @p cell corresponds to the immediate parent
2359 * cell of a set of newly created active cells.
2360 */
2361 boost::signals2::signal<void(
2362 const typename Triangulation<dim, spacedim>::cell_iterator &cell)>
2363 post_refinement_on_cell;
2364
2365 /**
2366 * This signal is triggered whenever the triangulation owning the signal
2367 * is copied by another triangulation using
2368 * Triangulation::copy_triangulation() (i.e. it is triggered on the
2369 * <i>old</i> triangulation, but the new one is passed as an argument).
2370 */
2371 boost::signals2::signal<void(
2372 const Triangulation<dim, spacedim> &destination_tria)>
2373 copy;
2374
2375 /**
2376 * This signal is triggered whenever the Triangulation::clear() function
2377 * is called and in the destructor of the triangulation. This signal is
2378 * also triggered when loading a triangulation from an archive via
2379 * Triangulation::load() as the previous content of the triangulation is
2380 * first destroyed.
2381 *
2382 * The signal is triggered before the data structures of the
2383 * triangulation are destroyed. In other words, the functions
2384 * attached to this signal get a last look at the triangulation,
2385 * for example to save information stored as part of the
2386 * triangulation.
2387 */
2388 boost::signals2::signal<void()> clear;
2389
2390 /**
2391 * This is a catch-all signal that is triggered whenever the create,
2392 * post_refinement, or clear signals are triggered. In effect, it can be
2393 * used to indicate to an object connected to the signal that the
2394 * triangulation has been changed, whatever the exact cause of the change.
2395 *
2396 * @note The cell-level signals @p pre_coarsening_on_cell and @p
2397 * post_refinement_on_cell are not connected to this signal.
2398 */
2399 boost::signals2::signal<void()> any_change;
2400
2401 /**
2402 * This signal is triggered for each cell during every automatic or manual
2403 * repartitioning. It is intended to allow a weighted repartitioning
2404 * of the domain to balance the computational load across processes in a
2405 * different way than balancing the number of cells. Any connected
2406 * function is expected to take an iterator to a cell, and a CellStatus
2407 * argument that indicates whether this cell is going to be refined,
2408 * coarsened or left untouched (see the documentation of the CellStatus
2409 * enum for more information). The function is expected to return an
2410 * unsigned integer, which is interpreted as the additional computational
2411 * load of this cell.
2412 *
2413 * In serial and parallel shared applications, partitioning happens after
2414 * refinement. So all cells will have the `CellStatus::cell_will_persist`
2415 * status.
2416 *
2417 * In parallel distributed applications, partitioning happens during
2418 * refinement. If this cell is going to be coarsened, the signal is called
2419 * for the parent cell and you need to provide the weight of the future
2420 * parent cell. If this cell is going to be refined, the function is called
2421 * on all children while `cell_iterator` refers to their parent cell. In
2422 * this case, you need to pick a weight for each individual child based on
2423 * information given by the parent cell.
2424 *
2425 * If several functions are connected to this signal, their return values
2426 * will be summed to calculate the final weight of a cell. This allows
2427 * different parts of a larger code base to have their own functions
2428 * computing the weight of a cell; for example in a code that does both
2429 * finite element and particle computations on each cell, the code could
2430 * separate the computation of a cell's weight into two functions, each
2431 * implemented in their respective files, that provide the finite
2432 * element-based and the particle-based weights.
2433 *
2434 * This function is used in step-68 and implicitly in step-75 using the
2435 * parallel::CellWeights class.
2436 */
2437 boost::signals2::signal<unsigned int(const cell_iterator &,
2438 const ::dealii::CellStatus),
2439 CellWeightSum<unsigned int>>
2440 weight;
2441
2442 /**
2443 * This signal is triggered at the beginning of execution of the
2444 * parallel::distributed::Triangulation::execute_coarsening_and_refinement()
2445 * function (which is
2446 * itself called by other functions such as Triangulation::refine_global()
2447 * ). At the time this signal is triggered, the triangulation is still
2448 * unchanged. This signal
2449 * is different from the pre_refinement signal, because in the parallel
2450 * distributed case the pre_refinement signal is triggered multiple times
2451 * without a way to distinguish the last signal call.
2452 */
2453 boost::signals2::signal<void()> pre_distributed_refinement;
2454
2455 /**
2456 * This signal is triggered during execution of the
2457 * parallel::distributed::Triangulation::execute_coarsening_and_refinement()
2458 * function. At the time this signal is triggered, the p4est oracle has been
2459 * refined and the cell relations have been updated. The triangulation is
2460 * unchanged otherwise, and the p4est oracle has not yet been repartitioned.
2461 */
2462 boost::signals2::signal<void()> post_p4est_refinement;
2463
2464 /**
2465 * This signal is triggered at the end of execution of the
2466 * parallel::distributed::Triangulation::execute_coarsening_and_refinement()
2467 * function when the triangulation has reached its final state. This signal
2468 * is different from the post_refinement signal, because in the parallel
2469 * distributed case the post_refinement signal is triggered multiple times
2470 * without a way to distinguish the last signal call.
2471 */
2472 boost::signals2::signal<void()> post_distributed_refinement;
2473
2474 /**
2475 * This signal is triggered at the beginning of execution of the
2476 * parallel::distributed::Triangulation::repartition() function. At the time
2477 * this signal is triggered, the triangulation is still unchanged.
2478 */
2479 boost::signals2::signal<void()> pre_distributed_repartition;
2480
2481 /**
2482 * This signal is triggered at the end of execution of the
2483 * parallel::distributed::Triangulation::repartition()
2484 * function when the triangulation has reached its final state.
2485 */
2486 boost::signals2::signal<void()> post_distributed_repartition;
2487
2488 /**
2489 * This signal is triggered at the beginning of execution of the
2490 * parallel::distributed::Triangulation::save()
2491 * function. At the time this signal is triggered, the triangulation
2492 * is still unchanged.
2493 */
2494 boost::signals2::signal<void()> pre_distributed_save;
2495
2496 /**
2497 * This signal is triggered at the end of execution of the
2498 * parallel::distributed::Triangulation::save()
2499 * function when the triangulation has reached its final state.
2500 */
2501 boost::signals2::signal<void()> post_distributed_save;
2502
2503 /**
2504 * This signal is triggered at the beginning of execution of the
2505 * parallel::distributed::Triangulation::load()
2506 * function. At the time this signal is triggered, the triangulation
2507 * is still unchanged.
2508 */
2509 boost::signals2::signal<void()> pre_distributed_load;
2510
2511 /**
2512 * This signal is triggered at the end of execution of the
2513 * parallel::distributed::Triangulation::load()
2514 * function when the triangulation has reached its final state.
2515 */
2516 boost::signals2::signal<void()> post_distributed_load;
2517 };
2518
2519 /**
2520 * @name Keeping up with what happens to a triangulation
2521 * @{
2522 */
2523
2524 /**
2525 * Signals for the various actions that a triangulation can do to itself.
2526 */
2527 mutable Signals signals;
2528
2529 /** @} */
2530
2531 /**
2532 * @name History of a triangulation
2533 * @{
2534 */
2535
2536 /**
2537 * Save the addresses of the cells which are flagged for refinement to @p
2538 * out. For usage, read the general documentation for this class.
2539 */
2540 void
2541 save_refine_flags(std::ostream &out) const;
2542
2543 /**
2544 * Same as above, but store the flags to a bitvector rather than to a file.
2545 */
2546 void
2547 save_refine_flags(std::vector<bool> &v) const;
2548
2549 /**
2550 * Read the information stored by @p save_refine_flags.
2551 */
2552 void
2553 load_refine_flags(std::istream &in);
2554
2555 /**
2556 * Read the information stored by @p save_refine_flags.
2557 */
2558 void
2559 load_refine_flags(const std::vector<bool> &v);
2560
2561 /**
2562 * Analogue to @p save_refine_flags.
2563 */
2564 void
2565 save_coarsen_flags(std::ostream &out) const;
2566
2567 /**
2568 * Same as above, but store the flags to a bitvector rather than to a file.
2569 */
2570 void
2571 save_coarsen_flags(std::vector<bool> &v) const;
2572
2573 /**
2574 * Analogue to @p load_refine_flags.
2575 */
2576 void
2577 load_coarsen_flags(std::istream &out);
2578
2579 /**
2580 * Analogue to @p load_refine_flags.
2581 */
2582 void
2583 load_coarsen_flags(const std::vector<bool> &v);
2584
2585 /**
2586 * Return whether this triangulation has ever undergone anisotropic (as
2587 * opposed to only isotropic) refinement.
2588 */
2589 bool
2590 get_anisotropic_refinement_flag() const;
2591
2592 /** @} */
2593
2594 /**
2595 * @name User data
2596 * @{
2597 */
2598
2599 /**
2600 * Clear all user flags. See also
2601 * @ref GlossUserFlags.
2602 */
2603 void
2604 clear_user_flags();
2605
2606 /**
2607 * Save all user flags. See the general documentation for this class and the
2608 * documentation for the @p save_refine_flags for more details. See also
2609 * @ref GlossUserFlags.
2610 */
2611 void
2612 save_user_flags(std::ostream &out) const;
2613
2614 /**
2615 * Same as above, but store the flags to a bitvector rather than to a file.
2616 * The output vector is resized if necessary. See also
2617 * @ref GlossUserFlags.
2618 */
2619 void
2620 save_user_flags(std::vector<bool> &v) const;
2621
2622 /**
2623 * Read the information stored by @p save_user_flags. See also
2624 * @ref GlossUserFlags.
2625 */
2626 void
2627 load_user_flags(std::istream &in);
2628
2629 /**
2630 * Read the information stored by @p save_user_flags. See also
2631 * @ref GlossUserFlags.
2632 */
2633 void
2634 load_user_flags(const std::vector<bool> &v);
2635
2636 /**
2637 * Clear all user flags on lines. See also
2638 * @ref GlossUserFlags.
2639 */
2640 void
2641 clear_user_flags_line();
2642
2643 /**
2644 * Save the user flags on lines. See also
2645 * @ref GlossUserFlags.
2646 */
2647 void
2648 save_user_flags_line(std::ostream &out) const;
2649
2650 /**
2651 * Same as above, but store the flags to a bitvector rather than to a file.
2652 * The output vector is resized if necessary. See also
2653 * @ref GlossUserFlags.
2654 */
2655 void
2656 save_user_flags_line(std::vector<bool> &v) const;
2657
2658 /**
2659 * Load the user flags located on lines. See also
2660 * @ref GlossUserFlags.
2661 */
2662 void
2663 load_user_flags_line(std::istream &in);
2664
2665 /**
2666 * Load the user flags located on lines. See also
2667 * @ref GlossUserFlags.
2668 */
2669 void
2670 load_user_flags_line(const std::vector<bool> &v);
2671
2672 /**
2673 * Clear all user flags on quads. See also
2674 * @ref GlossUserFlags.
2675 */
2676 void
2677 clear_user_flags_quad();
2678
2679 /**
2680 * Save the user flags on quads. See also
2681 * @ref GlossUserFlags.
2682 */
2683 void
2684 save_user_flags_quad(std::ostream &out) const;
2685
2686 /**
2687 * Same as above, but store the flags to a bitvector rather than to a file.
2688 * The output vector is resized if necessary. See also
2689 * @ref GlossUserFlags.
2690 */
2691 void
2692 save_user_flags_quad(std::vector<bool> &v) const;
2693
2694 /**
2695 * Load the user flags located on quads. See also
2696 * @ref GlossUserFlags.
2697 */
2698 void
2699 load_user_flags_quad(std::istream &in);
2700
2701 /**
2702 * Load the user flags located on quads. See also
2703 * @ref GlossUserFlags.
2704 */
2705 void
2706 load_user_flags_quad(const std::vector<bool> &v);
2707
2708
2709 /**
2710 * Clear all user flags on quads. See also
2711 * @ref GlossUserFlags.
2712 */
2713 void
2714 clear_user_flags_hex();
2715
2716 /**
2717 * Save the user flags on hexs. See also
2718 * @ref GlossUserFlags.
2719 */
2720 void
2721 save_user_flags_hex(std::ostream &out) const;
2722
2723 /**
2724 * Same as above, but store the flags to a bitvector rather than to a file.
2725 * The output vector is resized if necessary. See also
2726 * @ref GlossUserFlags.
2727 */
2728 void
2729 save_user_flags_hex(std::vector<bool> &v) const;
2730
2731 /**
2732 * Load the user flags located on hexs. See also
2733 * @ref GlossUserFlags.
2734 */
2735 void
2736 load_user_flags_hex(std::istream &in);
2737
2738 /**
2739 * Load the user flags located on hexs. See also
2740 * @ref GlossUserFlags.
2741 */
2742 void
2743 load_user_flags_hex(const std::vector<bool> &v);
2744
2745 /**
2746 * Clear all user pointers and indices and allow the use of both for next
2747 * access. See also
2748 * @ref GlossUserData.
2749 */
2750 void
2751 clear_user_data();
2752
2753 /**
2754 * Save all user indices. The output vector is resized if necessary. See
2755 * also
2756 * @ref GlossUserData.
2757 */
2758 void
2759 save_user_indices(std::vector<unsigned int> &v) const;
2760
2761 /**
2762 * Read the information stored by save_user_indices(). See also
2763 * @ref GlossUserData.
2764 */
2765 void
2766 load_user_indices(const std::vector<unsigned int> &v);
2767
2768 /**
2769 * Save all user pointers. The output vector is resized if necessary. See
2770 * also
2771 * @ref GlossUserData.
2772 */
2773 void
2774 save_user_pointers(std::vector<void *> &v) const;
2775
2776 /**
2777 * Read the information stored by save_user_pointers(). See also
2778 * @ref GlossUserData.
2779 */
2780 void
2781 load_user_pointers(const std::vector<void *> &v);
2782
2783 /**
2784 * Save the user indices on lines. The output vector is resized if
2785 * necessary. See also
2786 * @ref GlossUserData.
2787 */
2788 void
2789 save_user_indices_line(std::vector<unsigned int> &v) const;
2790
2791 /**
2792 * Load the user indices located on lines. See also
2793 * @ref GlossUserData.
2794 */
2795 void
2796 load_user_indices_line(const std::vector<unsigned int> &v);
2797
2798 /**
2799 * Save the user indices on quads. The output vector is resized if
2800 * necessary. See also
2801 * @ref GlossUserData.
2802 */
2803 void
2804 save_user_indices_quad(std::vector<unsigned int> &v) const;
2805
2806 /**
2807 * Load the user indices located on quads. See also
2808 * @ref GlossUserData.
2809 */
2810 void
2811 load_user_indices_quad(const std::vector<unsigned int> &v);
2812
2813 /**
2814 * Save the user indices on hexes. The output vector is resized if
2815 * necessary. See also
2816 * @ref GlossUserData.
2817 */
2818 void
2819 save_user_indices_hex(std::vector<unsigned int> &v) const;
2820
2821 /**
2822 * Load the user indices located on hexs. See also
2823 * @ref GlossUserData.
2824 */
2825 void
2826 load_user_indices_hex(const std::vector<unsigned int> &v);
2827 /**
2828 * Save the user indices on lines. The output vector is resized if
2829 * necessary. See also
2830 * @ref GlossUserData.
2831 */
2832 void
2833 save_user_pointers_line(std::vector<void *> &v) const;
2834
2835 /**
2836 * Load the user pointers located on lines. See also
2837 * @ref GlossUserData.
2838 */
2839 void
2840 load_user_pointers_line(const std::vector<void *> &v);
2841
2842 /**
2843 * Save the user pointers on quads. The output vector is resized if
2844 * necessary. See also
2845 * @ref GlossUserData.
2846 */
2847 void
2848 save_user_pointers_quad(std::vector<void *> &v) const;
2849
2850 /**
2851 * Load the user pointers located on quads. See also
2852 * @ref GlossUserData.
2853 */
2854 void
2855 load_user_pointers_quad(const std::vector<void *> &v);
2856
2857 /**
2858 * Save the user pointers on hexes. The output vector is resized if
2859 * necessary. See also
2860 * @ref GlossUserData.
2861 */
2862 void
2863 save_user_pointers_hex(std::vector<void *> &v) const;
2864
2865 /**
2866 * Load the user pointers located on hexs. See also
2867 * @ref GlossUserData.
2868 */
2869 void
2870 load_user_pointers_hex(const std::vector<void *> &v);
2871
2872 /** @} */
2873
2874 /**
2875 * @name Cell iterator functions
2876 * @{
2877 */
2878
2879 /**
2880 * Iterator to the first used cell on level @p level.
2881 *
2882 * @note The given @p level argument needs to correspond to a level of the
2883 * triangulation, i.e., should be less than the value returned by
2884 * n_levels(). On the other hand, for parallel computations using
2885 * a parallel::distributed::Triangulation object, it is often convenient
2886 * to write loops over the cells of all levels of the global mesh, even
2887 * if the <i>local</i> portion of the triangulation does not actually
2888 * have cells at one of the higher levels. In those cases, the
2889 * @p level argument is accepted if it is less than what the
2890 * n_global_levels() function returns. If the given @p level is
2891 * between the values returned by n_levels() and n_global_levels(),
2892 * then no cells exist in the local portion of the triangulation
2893 * at this level, and the function simply returns what end() would
2894 * return.
2895 */
2896 cell_iterator
2897 begin(const unsigned int level = 0) const;
2898
2899 /**
2900 * Iterator to the first active cell on level @p level. If the given level
2901 * does not contain any active cells (i.e., all cells on this level are
2902 * further refined, then this function returns
2903 * <code>end_active(level)</code> so that loops of the kind
2904 * @code
2905 * for (const auto cell=tria.begin_active(level);
2906 * cell!=tria.end_active(level);
2907 * ++cell)
2908 * {
2909 * ...
2910 * }
2911 * @endcode
2912 * have zero iterations, as may be expected if there are no active cells on
2913 * this level.
2914 *
2915 * @note The given @p level argument needs to correspond to a level of the
2916 * triangulation, i.e., should be less than the value returned by
2917 * n_levels(). On the other hand, for parallel computations using
2918 * a parallel::distributed::Triangulation object, it is often convenient
2919 * to write loops over the cells of all levels of the global mesh, even
2920 * if the <i>local</i> portion of the triangulation does not actually
2921 * have cells at one of the higher levels. In those cases, the
2922 * @p level argument is accepted if it is less than what the
2923 * n_global_levels() function returns. If the given @p level is
2924 * between the values returned by n_levels() and n_global_levels(),
2925 * then no cells exist in the local portion of the triangulation
2926 * at this level, and the function simply returns what end() would
2927 * return.
2928 */
2929 active_cell_iterator
2930 begin_active(const unsigned int level = 0) const;
2931
2932 /**
2933 * Iterator past the end; this iterator serves for comparisons of iterators
2934 * with past-the-end or before-the-beginning states.
2935 */
2936 cell_iterator
2937 end() const;
2938
2939 /**
2940 * Return an iterator which is the first iterator not on level. If @p level
2941 * is the last level, then this returns <tt>end()</tt>.
2942 *
2943 * @note The given @p level argument needs to correspond to a level of the
2944 * triangulation, i.e., should be less than the value returned by
2945 * n_levels(). On the other hand, for parallel computations using
2946 * a parallel::distributed::Triangulation object, it is often convenient
2947 * to write loops over the cells of all levels of the global mesh, even
2948 * if the <i>local</i> portion of the triangulation does not actually
2949 * have cells at one of the higher levels. In those cases, the
2950 * @p level argument is accepted if it is less than what the
2951 * n_global_levels() function returns. If the given @p level is
2952 * between the values returned by n_levels() and n_global_levels(),
2953 * then no cells exist in the local portion of the triangulation
2954 * at this level, and the function simply returns what end() would
2955 * return.
2956 */
2957 cell_iterator
2958 end(const unsigned int level) const;
2959
2960 /**
2961 * Return an active iterator which is the first active iterator not on the
2962 * given level. If @p level is the last level, then this returns
2963 * <tt>end()</tt>.
2964 *
2965 * @note The given @p level argument needs to correspond to a level of the
2966 * triangulation, i.e., should be less than the value returned by
2967 * n_levels(). On the other hand, for parallel computations using
2968 * a parallel::distributed::Triangulation object, it is often convenient
2969 * to write loops over the cells of all levels of the global mesh, even
2970 * if the <i>local</i> portion of the triangulation does not actually
2971 * have cells at one of the higher levels. In those cases, the
2972 * @p level argument is accepted if it is less than what the
2973 * n_global_levels() function returns. If the given @p level is
2974 * between the values returned by n_levels() and n_global_levels(),
2975 * then no cells exist in the local portion of the triangulation
2976 * at this level, and the function simply returns what end() would
2977 * return.
2978 */
2979 active_cell_iterator
2980 end_active(const unsigned int level) const;
2981
2982
2983 /**
2984 * Return an iterator pointing to the last used cell.
2985 */
2986 cell_iterator
2987 last() const;
2988
2989 /**
2990 * Return an iterator pointing to the last active cell.
2991 */
2992 active_cell_iterator
2993 last_active() const;
2994
2995 /**
2996 * Return an iterator to a cell of this Triangulation object constructed from
2997 * an independent CellId object.
2998 *
2999 * @note See the documentation of contains_cell() about which CellId objects
3000 * are valid.
3001 */
3002 cell_iterator
3003 create_cell_iterator(const CellId &cell_id) const;
3004
3005 /**
3006 * Check if the triangulation contains a cell with the id @p cell_id.
3007 * If the given argument corresponds to a valid cell in this triangulation,
3008 * this operation will always return true for sequential triangulations where
3009 * the current processor stores all cells that are part of the triangulation.
3010 * On the other hand, if this is a parallel triangulation, then the current
3011 * processor may not actually know about this cell. In this case, this
3012 * operation will return true for locally relevant cells, but may return false
3013 * for artificial cells that are less refined on the current processor.
3014 */
3015 bool
3016 contains_cell(const CellId &cell_id) const;
3017 /** @} */
3018
3019 /**
3020 * @name Cell iterator functions returning ranges of iterators
3021 * @{
3022 */
3023
3024 /**
3025 * Return an iterator range that contains all cells (active or not) that
3026 * make up this triangulation. Such a range is useful to initialize
3027 * range-based for loops as supported by C++11. See the example in the
3028 * documentation of active_cell_iterators().
3029 *
3030 * @return The half open range <code>[this->begin(), this->end())</code>
3031 *
3032 * @ingroup CPP11
3033 */
3034 IteratorRange<cell_iterator>
3035 cell_iterators() const;
3036
3037 /**
3038 * Return an iterator range that contains all active cells that make up this
3039 * triangulation. Such a range is useful to initialize range-based for loops
3040 * as supported by C++11, see also
3041 * @ref CPP11 "C++11 standard".
3042 *
3043 * Range-based for loops are useful in that they require much less code than
3044 * traditional loops (see <a href="http://en.wikipedia.org/wiki/C%2B%2B11
3045 * #Range-based_for_loop">here</a> for a discussion of how they work). An
3046 * example is that without range-based for loops, one often writes code such
3047 * as the following (assuming for a moment that our goal is setting the user
3048 * flag on every active cell):
3049 * @code
3050 * Triangulation<dim> triangulation;
3051 * ...
3052 * typename Triangulation<dim>::active_cell_iterator
3053 * cell = triangulation.begin_active(),
3054 * endc = triangulation.end();
3055 * for (; cell!=endc; ++cell)
3056 * cell->set_user_flag();
3057 * @endcode
3058 * Using C++11's range-based for loops, this is now entirely equivalent to
3059 * the following:
3060 * @code
3061 * Triangulation<dim> triangulation;
3062 * ...
3063 * for (const auto &cell : triangulation.active_cell_iterators())
3064 * cell->set_user_flag();
3065 * @endcode
3066 *
3067 * @return The half open range <code>[this->begin_active(),
3068 * this->end())</code>
3069 *
3070 * @ingroup CPP11
3071 */
3072 IteratorRange<active_cell_iterator>
3073 active_cell_iterators() const;
3074
3075 /**
3076 * Return an iterator range that contains all cells (active or not) that
3077 * make up the given level of this triangulation. Such a range is useful to
3078 * initialize range-based for loops as supported by C++11. See the example
3079 * in the documentation of active_cell_iterators().
3080 *
3081 * @param[in] level A given level in the refinement hierarchy of this
3082 * triangulation.
3083 * @return The half open range <code>[this->begin(level),
3084 * this->end(level))</code>
3085 *
3086 * @pre level must be less than this->n_levels().
3087 *
3088 * @ingroup CPP11
3089 */
3090 IteratorRange<cell_iterator>
3091 cell_iterators_on_level(const unsigned int level) const;
3092
3093 /**
3094 * Return an iterator range that contains all active cells that make up the
3095 * given level of this triangulation. Such a range is useful to initialize
3096 * range-based for loops as supported by C++11. See the example in the
3097 * documentation of active_cell_iterators().
3098 *
3099 * @param[in] level A given level in the refinement hierarchy of this
3100 * triangulation.
3101 * @return The half open range <code>[this->begin_active(level),
3102 * this->end(level))</code>
3103 *
3104 * @pre level must be less than this->n_levels().
3105 *
3106 * @ingroup CPP11
3107 */
3108 IteratorRange<active_cell_iterator>
3109 active_cell_iterators_on_level(const unsigned int level) const;
3110
3111 /** @} */
3112
3113 /*-------------------------------------------------------------------------*/
3114
3115 /**
3116 * @name Face iterator functions
3117 * @{
3118 */
3119
3120 /**
3121 * Iterator to the first used face.
3122 */
3123 face_iterator
3124 begin_face() const;
3125
3126 /**
3127 * Iterator to the first active face.
3128 */
3129 active_face_iterator
3130 begin_active_face() const;
3131
3132 /**
3133 * Iterator past the end; this iterator serves for comparisons of iterators
3134 * with past-the-end or before-the-beginning states.
3135 */
3136 face_iterator
3137 end_face() const;
3138
3139 /**
3140 * Return an iterator range that contains all active faces that make up this
3141 * triangulation. This function is the face version of
3142 * Triangulation::active_cell_iterators(), and allows one to write code
3143 * like, e.g.,
3144 *
3145 * @code
3146 * Triangulation<dim> triangulation;
3147 * ...
3148 * for (auto &face : triangulation.active_face_iterators())
3149 * face->set_manifold_id(42);
3150 * @endcode
3151 *
3152 * @return The half open range <code>[this->begin_active_face(),
3153 * this->end_face())</code>
3154 *
3155 * @ingroup CPP11
3156 */
3157 IteratorRange<active_face_iterator>
3158 active_face_iterators() const;
3159
3160 /** @} */
3161
3162 /*-------------------------------------------------------------------------*/
3163
3164 /**
3165 * @name Vertex iterator functions
3166 * @{
3167 */
3168
3169 /**
3170 * Iterator to the first used vertex. This function can only be used if dim
3171 * is not one.
3172 */
3173 vertex_iterator
3174 begin_vertex() const;
3175
3176 /**
3177 * Iterator to the first active vertex. Because all vertices are active,
3178 * begin_vertex() and begin_active_vertex() return the same vertex. This
3179 * function can only be used if dim is not one.
3180 */
3181 active_vertex_iterator
3182 begin_active_vertex() const;
3183
3184 /**
3185 * Iterator past the end; this iterator serves for comparisons of iterators
3186 * with past-the-end or before-the-beginning states. This function can only
3187 * be used if dim is not one.
3188 */
3189 vertex_iterator
3190 end_vertex() const;
3191
3192 /** @} */
3193
3194 /**
3195 * @name Information about the triangulation
3196 * @{
3197 */
3198
3199 /**
3200 * In the following, most functions are provided in two versions, with and
3201 * without an argument describing the level. The versions with this argument
3202 * are only applicable for objects describing the cells of the present
3203 * triangulation. For example: in 2d <tt>n_lines(level)</tt> cannot be
3204 * called, only <tt>n_lines()</tt>, as lines are faces in 2d and therefore
3205 * have no level.
3206 */
3207
3208 /**
3209 * Return the total number of used lines, active or not.
3210 */
3211 unsigned int
3212 n_lines() const;
3213
3214 /**
3215 * Return the total number of used lines, active or not on level @p level.
3216 */
3217 unsigned int
3218 n_lines(const unsigned int level) const;
3219
3220 /**
3221 * Return the total number of active lines.
3222 */
3223 unsigned int
3224 n_active_lines() const;
3225
3226 /**
3227 * Return the total number of active lines, on level @p level.
3228 */
3229 unsigned int
3230 n_active_lines(const unsigned int level) const;
3231
3232 /**
3233 * Return the total number of used quads, active or not.
3234 */
3235 unsigned int
3236 n_quads() const;
3237
3238 /**
3239 * Return the total number of used quads, active or not on level @p level.
3240 */
3241 unsigned int
3242 n_quads(const unsigned int level) const;
3243
3244 /**
3245 * Return the total number of active quads, active or not.
3246 */
3247 unsigned int
3248 n_active_quads() const;
3249
3250 /**
3251 * Return the total number of active quads, active or not on level @p level.
3252 */
3253 unsigned int
3254 n_active_quads(const unsigned int level) const;
3255
3256 /**
3257 * Return the total number of used hexahedra, active or not.
3258 */
3259 unsigned int
3260 n_hexs() const;
3261
3262 /**
3263 * Return the total number of used hexahedra, active or not on level @p
3264 * level.
3265 */
3266 unsigned int
3267 n_hexs(const unsigned int level) const;
3268
3269 /**
3270 * Return the total number of active hexahedra, active or not.
3271 */
3272 unsigned int
3273 n_active_hexs() const;
3274
3275 /**
3276 * Return the total number of active hexahedra, active or not on level @p
3277 * level.
3278 */
3279 unsigned int
3280 n_active_hexs(const unsigned int level) const;
3281
3282 /**
3283 * Return the total number of used cells, active or not. Maps to
3284 * <tt>n_lines()</tt> in one space dimension and so on.
3285 */
3286 unsigned int
3287 n_cells() const;
3288
3289 /**
3290 * Return the total number of used cells, active or not, on level @p level.
3291 * Maps to <tt>n_lines(level)</tt> in one space dimension and so on.
3292 */
3293 unsigned int
3294 n_cells(const unsigned int level) const;
3295
3296 /**
3297 * Return the total number of active cells. Maps to
3298 * <tt>n_active_lines()</tt> in one space dimension and so on.
3299 */
3300 unsigned int
3301 n_active_cells() const;
3302
3303 /**
3304 * Return the total number of active cells. For the current class, this is
3305 * the same as n_active_cells(). However, the function may be overloaded in
3306 * derived classes (e.g., in parallel::distributed::Triangulation) where it
3307 * may return a value greater than the number of active cells reported by
3308 * the triangulation object on the current processor.
3309 */
3310 virtual types::global_cell_index
3311 n_global_active_cells() const;
3312
3313
3314 /**
3315 * Return the total number of active cells on level @p level. Maps to
3316 * <tt>n_active_lines(level)</tt> in one space dimension and so on.
3317 */
3318 unsigned int
3319 n_active_cells(const unsigned int level) const;
3320
3321 /**
3322 * Return the total number of coarse cells. If the coarse mesh is replicated
3323 * on each process, this simply returns <tt>n_cells(0)</tt>.
3324 */
3325 virtual types::coarse_cell_id
3326 n_global_coarse_cells() const;
3327
3328 /**
3329 * Return the total number of used faces, active or not. In 2d, the result
3330 * equals n_lines(), in 3d it equals n_quads(), while in 1d it equals
3331 * the number of used vertices.
3332 */
3333 unsigned int
3334 n_faces() const;
3335
3336 /**
3337 * Return the total number of active faces. In 2d, the result equals
3338 * n_active_lines(), in 3d it equals n_active_quads(), while in 1d it equals
3339 * the number of used vertices.
3340 */
3341 unsigned int
3342 n_active_faces() const;
3343
3344 /**
3345 * Return the number of levels in this triangulation.
3346 *
3347 * @note Internally, triangulations store data in levels, and there may be
3348 * more levels in this data structure than one may think -- for example,
3349 * imagine a triangulation that we just got by coarsening the highest level
3350 * so that it was completely depopulated. That level is not removed, since
3351 * it will most likely be repopulated soon by the next refinement process.
3352 * As a consequence, if you happened to run through raw cell iterators
3353 * (which you can't do as a user of this class, but can internally), then
3354 * the number of objects in the levels hierarchy is larger than the level of
3355 * the most refined cell plus one. On the other hand, since this is rarely
3356 * what a user of this class cares about, the function really just returns
3357 * the level of the most refined active cell plus one. (The plus one is
3358 * because in a coarse, unrefined mesh, all cells have level zero -- making
3359 * the number of levels equal to one.)
3360 */
3361 unsigned int
3362 n_levels() const;
3363
3364 /**
3365 * Return the number of levels in use. This function is equivalent to
3366 * n_levels() for a serial Triangulation, but gives the maximum of
3367 * n_levels() over all processors for a parallel::distributed::Triangulation
3368 * and therefore can be larger than n_levels().
3369 */
3370 virtual unsigned int
3371 n_global_levels() const;
3372
3373 /**
3374 * Return true if the triangulation has hanging nodes.
3375 *
3376 * The function is made virtual since the result can be interpreted in
3377 * different ways, depending on whether the triangulation lives only on a
3378 * single processor, or may be distributed as done in the
3379 * parallel::distributed::Triangulation class (see there for a description
3380 * of what the function is supposed to do in the parallel context).
3381 */
3382 virtual bool
3383 has_hanging_nodes() const;
3384
3385 /**
3386 * Return the total number of vertices. Some of them may not be used, which
3387 * usually happens upon coarsening of a triangulation when some vertices are
3388 * discarded, but we do not want to renumber the remaining ones, leading to
3389 * holes in the numbers of used vertices. You can get the number of used
3390 * vertices using @p n_used_vertices function.
3391 */
3392 unsigned int
3393 n_vertices() const;
3394
3395 /**
3396 * Return a constant reference to all the vertices present in this
3397 * triangulation. Note that not necessarily all vertices in this array are
3398 * actually used; for example, if you coarsen a mesh, then some vertices are
3399 * deleted, but their positions in this array are unchanged as the indices
3400 * of vertices are only allocated once. You can find out about which
3401 * vertices are actually used by the function get_used_vertices().
3402 */
3403 const std::vector<Point<spacedim>> &
3404 get_vertices() const;
3405
3406 /**
3407 * Return the number of vertices that are presently in use, i.e. belong to
3408 * at least one used element.
3409 */
3410 unsigned int
3411 n_used_vertices() const;
3412
3413 /**
3414 * Return @p true if the vertex with this @p index is used.
3415 */
3416 bool
3417 vertex_used(const unsigned int index) const;
3418
3419 /**
3420 * Return a constant reference to the array of @p bools indicating whether
3421 * an entry in the vertex array is used or not.
3422 */
3423 const std::vector<bool> &
3424 get_used_vertices() const;
3425
3426 /**
3427 * Return the maximum number of cells meeting at a common vertex. Since this
3428 * number is an invariant under refinement, only the cells on the coarsest
3429 * level are considered. The operation is thus reasonably fast. The
3430 * invariance is only true for sufficiently many cells in the coarsest
3431 * triangulation (e.g. for a single cell one would be returned), so a
3432 * minimum of four is returned in two dimensions, 8 in three dimensions,
3433 * etc, which is how many cells meet if the triangulation is refined.
3434 *
3435 * In one space dimension, two is returned.
3436 */
3437 unsigned int
3438 max_adjacent_cells() const;
3439
3440 /**
3441 * This function always returns @p invalid_subdomain_id but is there for
3442 * compatibility with the derived @p parallel::distributed::Triangulation
3443 * class. For distributed parallel triangulations this function returns the
3444 * subdomain id of those cells that are owned by the current processor.
3445 */
3446 virtual types::subdomain_id
3447 locally_owned_subdomain() const;
3448
3449 /**
3450 * Return a reference to the current object.
3451 *
3452 * This doesn't seem to be very useful but allows to write code that can
3453 * access the underlying triangulation for anything that satisfies the
3454 * @ref ConceptMeshType "MeshType concept"
3455 * (which may not only be a triangulation, but also a DoFHandler, for
3456 * example).
3457 */
3458 Triangulation<dim, spacedim> &
3459 get_triangulation();
3460
3461 /**
3462 * Return a reference to the current object. This is the const-version of
3463 * the previous function.
3464 */
3465 const Triangulation<dim, spacedim> &
3466 get_triangulation() const;
3467
3468
3469 /** @} */
3470
3471 /**
3472 * @name Internal information about the number of objects
3473 * @{
3474 */
3475
3476 /**
3477 * Total number of lines, used or unused.
3478 *
3479 * @note This function really exports internal information about the
3480 * triangulation. It shouldn't be used in applications. The function is only
3481 * part of the public interface of this class because it is used in some of
3482 * the other classes that build very closely on it (in particular, the
3483 * DoFHandler class).
3484 */
3485 unsigned int
3486 n_raw_lines() const;
3487
3488 /**
3489 * Number of lines, used or unused, on the given level.
3490 *
3491 * @note This function really exports internal information about the
3492 * triangulation. It shouldn't be used in applications. The function is only
3493 * part of the public interface of this class because it is used in some of
3494 * the other classes that build very closely on it (in particular, the
3495 * DoFHandler class).
3496 */
3497 unsigned int
3498 n_raw_lines(const unsigned int level) const;
3499
3500 /**
3501 * Total number of quads, used or unused.
3502 *
3503 * @note This function really exports internal information about the
3504 * triangulation. It shouldn't be used in applications. The function is only
3505 * part of the public interface of this class because it is used in some of
3506 * the other classes that build very closely on it (in particular, the
3507 * DoFHandler class).
3508 */
3509 unsigned int
3510 n_raw_quads() const;
3511
3512 /**
3513 * Number of quads, used or unused, on the given level.
3514 *
3515 * @note This function really exports internal information about the
3516 * triangulation. It shouldn't be used in applications. The function is only
3517 * part of the public interface of this class because it is used in some of
3518 * the other classes that build very closely on it (in particular, the
3519 * DoFHandler class).
3520 */
3521 unsigned int
3522 n_raw_quads(const unsigned int level) const;
3523
3524 /**
3525 * Number of hexs, used or unused, on the given level.
3526 *
3527 * @note This function really exports internal information about the
3528 * triangulation. It shouldn't be used in applications. The function is only
3529 * part of the public interface of this class because it is used in some of
3530 * the other classes that build very closely on it (in particular, the
3531 * DoFHandler class).
3532 */
3533 unsigned int
3534 n_raw_hexs(const unsigned int level) const;
3535
3536 /**
3537 * Number of cells, used or unused, on the given level.
3538 *
3539 * @note This function really exports internal information about the
3540 * triangulation. It shouldn't be used in applications. The function is only
3541 * part of the public interface of this class because it is used in some of
3542 * the other classes that build very closely on it (in particular, the
3543 * DoFHandler class).
3544 */
3545 unsigned int
3546 n_raw_cells(const unsigned int level) const;
3547
3548 /**
3549 * Return the total number of faces, used or not. In 2d, the result equals
3550 * n_raw_lines(), in 3d it equals n_raw_quads(), while in 1d it equals
3551 * the number of vertices.
3552 *
3553 * @note This function really exports internal information about the
3554 * triangulation. It shouldn't be used in applications. The function is only
3555 * part of the public interface of this class because it is used in some of
3556 * the other classes that build very closely on it (in particular, the
3557 * DoFHandler class).
3558 */
3559 unsigned int
3560 n_raw_faces() const;
3561
3562 /** @} */
3563
3564 /**
3565 * Determine an estimate for the memory consumption (in bytes) of this
3566 * object.
3567 *
3568 * This function is made virtual, since a triangulation object might be
3569 * accessed through a pointer to this base class, even if the actual object
3570 * is a derived class.
3571 */
3572 virtual std::size_t
3573 memory_consumption() const;
3574
3575 /**
3576 * Write the data of this object to a stream for the purpose of
3577 * serialization using the [BOOST serialization
3578 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
3579 *
3580 * @note This function does not save <i>all</i> member variables of the
3581 * current triangulation. Rather, only certain kinds of information are
3582 * stored. For more information see the general documentation of this class.
3583 */
3584 template <class Archive>
3585 void
3586 save(Archive &ar, const unsigned int version) const;
3587
3588 /**
3589 * Read the data of this object from a stream for the purpose of
3590 * serialization using the [BOOST serialization
3591 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
3592 * Throw away the previous content.
3593 *
3594 * @note This function does not reset <i>all</i> member variables of the
3595 * current triangulation to the ones of the triangulation that was
3596 * previously stored to an archive. Rather, only certain kinds of
3597 * information are loaded. For more information see the general
3598 * documentation of this class.
3599 *
3600 * @note This function calls the Triangulation::clear() function and
3601 * consequently triggers the "clear" signal. After loading all data from the
3602 * archive, it then triggers the "create" signal. For more information on
3603 * signals, see the general documentation of this class.
3604 */
3605 template <class Archive>
3606 void
3607 load(Archive &ar, const unsigned int version);
3608
3609
3610 /**
3611 * Save the mesh and associated information into a number of files
3612 * that all use the provided basename as a starting prefix, plus some
3613 * suffixes that indicate the specific use of that file.
3614 *
3615 * Save the triangulation into the given file. Internally, this
3616 * function calls the save function which uses BOOST archives.
3617 */
3618 virtual void
3619 save(const std::string &file_basename) const;
3620
3621 /**
3622 * Load the triangulation saved with save() back in.
3623 */
3624 virtual void
3625 load(const std::string &file_basename);
3626
3627
3628 /**
3629 * Declare the (coarse) face pairs given in the argument of this function as
3630 * periodic. This way it is possible to obtain neighbors across periodic
3631 * boundaries.
3632 *
3633 * The vector can be filled by the function
3634 * GridTools::collect_periodic_faces.
3635 *
3636 * For more information on periodic boundary conditions see
3637 * GridTools::collect_periodic_faces, DoFTools::make_periodicity_constraints
3638 * and step-45.
3639 *
3640 * @note Before this function can be used the Triangulation has to be
3641 * initialized and must not be refined.
3642 */
3643 virtual void
3644 add_periodicity(
3645 const std::vector<GridTools::PeriodicFacePair<cell_iterator>> &);
3646
3647 /**
3648 * Return the periodic_face_map.
3649 */
3650 const std::map<std::pair<cell_iterator, unsigned int>,
3651 std::pair<std::pair<cell_iterator, unsigned int>,
3652 types::geometric_orientation>> &
3653 get_periodic_face_map() const;
3654
3655 /**
3656 * Return vector filled with the used reference-cell types of this
3657 * triangulation.
3658 */
3659 const std::vector<ReferenceCell> &
3660 get_reference_cells() const;
3661
3662 /**
3663 * Indicate if the triangulation only consists of hypercube-like cells, i.e.,
3664 * lines, quadrilaterals, or hexahedra.
3665 */
3666 bool
3667 all_reference_cells_are_hyper_cube() const;
3668
3669 /**
3670 * Indicate if the triangulation only consists of simplex-like cells, i.e.,
3671 * lines, triangles, or tetrahedra.
3672 */
3673 bool
3674 all_reference_cells_are_simplex() const;
3675
3676 /**
3677 * Indicate if the triangulation consists of different cell types (mix of
3678 * simplices, hypercubes, ...) or different face types, as in the case
3679 * of pyramids or wedges..
3680 */
3681 bool
3682 is_mixed_mesh() const;
3683
3684 #ifdef DOXYGEN
3685 /**
3686 * Write and read the data of this object from a stream for the purpose
3687 * of serialization. using the [BOOST serialization
3688 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
3689 *
3690 * This function is used in step-83.
3691 */
3692 template <class Archive>
3693 void
3694 serialize(Archive &archive, const unsigned int version);
3695 #else
3696 // This macro defines the serialize() method that is compatible with
3697 // the templated save() and load() method that have been implemented.
3698 BOOST_SERIALIZATION_SPLIT_MEMBER()
3699 #endif
3700
3701 /**
3702 * @name Serialization facilities.
3703 * @{
3704 */
3705 public:
3706 /**
3707 * Register a function that can be used to attach data of fixed size
3708 * to cells. This is useful for two purposes: (i) Upon refinement and
3709 * coarsening of a triangulation (@a e.g. in
3710 * parallel::distributed::Triangulation::execute_coarsening_and_refinement()),
3711 * one needs to be able to store one or more data vectors per cell that
3712 * characterizes the solution values on the cell so that this data can
3713 * then be transferred to the new owning processor of the cell (or
3714 * its parent/children) when the mesh is re-partitioned; (ii) when
3715 * serializing a computation to a file, it is necessary to attach
3716 * data to cells so that it can be saved (@a e.g. in
3717 * parallel::distributed::Triangulation::save()) along with the cell's
3718 * other information and, if necessary, later be reloaded from disk
3719 * with a different subdivision of cells among the processors.
3720 *
3721 * The way this function works is that it allows any number of interest
3722 * parties to register their intent to attach data to cells. One example
3723 * of classes that do this is parallel::distributed::SolutionTransfer
3724 * where each parallel::distributed::SolutionTransfer object that works
3725 * on the current Triangulation object then needs to register its intent.
3726 * Each of these parties registers a callback function (the first
3727 * argument here, @p pack_callback) that will be called whenever the
3728 * triangulation's execute_coarsening_and_refinement() or save()
3729 * functions are called.
3730 *
3731 * The current function then returns an integer handle that corresponds
3732 * to the number of data set that the callback provided here will attach.
3733 * While this number could be given a precise meaning, this is
3734 * not important: You will never actually have to do anything with
3735 * this number except return it to the notify_ready_to_unpack() function.
3736 * In other words, each interested party (i.e., the caller of the current
3737 * function) needs to store their respective returned handle for later use
3738 * when unpacking data in the callback provided to
3739 * notify_ready_to_unpack().
3740 *
3741 * Whenever @p pack_callback is then called by
3742 * execute_coarsening_and_refinement() or load() on a given cell, it
3743 * receives a number of arguments. In particular, the first
3744 * argument passed to the callback indicates the cell for which
3745 * it is supposed to attach data. This is always an active cell.
3746 *
3747 * The second, CellStatus, argument provided to the callback function
3748 * will tell you if the given cell will be coarsened, refined, or will
3749 * persist as is. (This status may be different than the refinement
3750 * or coarsening flags set on that cell, to accommodate things such as
3751 * the "one hanging node per edge" rule.). These flags need to be
3752 * read in context with the p4est quadrant they belong to, as their
3753 * relations are gathered in local_cell_relations.
3754 *
3755 * Specifically, the values for this argument mean the following:
3756 *
3757 * - `CellStatus::cell_will_persist`: The cell won't be refined/coarsened, but
3758 * might be moved to a different processor. If this is the case, the callback
3759 * will want to pack up the data on this cell into an array and store
3760 * it at the provided address for later unpacking wherever this cell
3761 * may land.
3762 * - `CellStatus::cell_will_be_refined`: This cell will be refined into 4 or 8
3763 * cells (in 2d and 3d, respectively). However, because these children don't
3764 * exist yet, you cannot access them at the time when the callback is called.
3765 * Thus, in local_cell_relations, the corresponding p4est quadrants of the
3766 * children cells are linked to the deal.II cell which is going to be refined.
3767 * To be specific, only the very first child is marked with
3768 * `CellStatus::cell_will_be_refined`, whereas the others will be marked with
3769 * `CellStatus::cell_invalid`, which indicates that these cells will be
3770 * ignored by default during the packing or unpacking process. This
3771 * ensures that data is only transferred once onto or from the parent
3772 * cell. If the callback is called with `CellStatus::cell_will_be_refined`,
3773 * the callback will want to pack up the data on this cell into an array and
3774 * store it at the provided address for later unpacking in a way so that it
3775 * can then be transferred to the children of the cell that will then be
3776 * available. In other words, if the data the callback will want to pack up
3777 * corresponds to a finite element field, then the prolongation from parent to
3778 * (new) children will have to happen during unpacking.
3779 * - `CellStatus::children_will_be_coarsened`: The children of this cell will
3780 * be coarsened into the given cell. These children still exist, so if this is
3781 * the value given to the callback as second argument, the callback will want
3782 * to transfer data from the children to the current parent cell and
3783 * pack it up so that it can later be unpacked again on a cell that
3784 * then no longer has any children (and may also be located on a
3785 * different processor). In other words, if the data the callback
3786 * will want to pack up corresponds to a finite element field, then
3787 * it will need to do the restriction from children to parent at
3788 * this point.
3789 * - `CellStatus::cell_invalid`: See `CellStatus::cell_will_be_refined`.
3790 *
3791 * @note If this function is used for serialization of data
3792 * using save() and load(), then the cell status argument with which
3793 * the callback is called will always be `CellStatus::cell_will_persist`.
3794 *
3795 * The callback function is expected to return a memory chunk of the
3796 * format `std::vector<char>`, representing the packed data on a
3797 * certain cell.
3798 *
3799 * The second parameter @p returns_variable_size_data indicates whether
3800 * the returned size of the memory region from the callback function
3801 * varies by cell (<tt>=true</tt>) or stays constant on each one
3802 * throughout the whole domain (<tt>=false</tt>).
3803 *
3804 * @note The purpose of this function is to register intent to
3805 * attach data for a single, subsequent call to
3806 * execute_coarsening_and_refinement() and notify_ready_to_unpack(),
3807 * save(), load(). Consequently, notify_ready_to_unpack(), save(),
3808 * and load() all forget the registered callbacks once these
3809 * callbacks have been called, and you will have to re-register
3810 * them with a triangulation if you want them to be active for
3811 * another call to these functions.
3812 */
3813 unsigned int
3814 register_data_attach(
3815 const std::function<std::vector<char>(const cell_iterator &,
3816 const ::dealii::CellStatus)>
3817 &pack_callback,
3818 const bool returns_variable_size_data);
3819
3820 /**
3821 * This function is the opposite of register_data_attach(). It is called
3822 * <i>after</i> the execute_coarsening_and_refinement() or save()/load()
3823 * functions are done when classes and functions that have previously
3824 * attached data to a triangulation for either transfer to other
3825 * processors, across mesh refinement, or serialization of data to
3826 * a file are ready to receive that data back. The important part about
3827 * this process is that the triangulation cannot do this right away from
3828 * the end of execute_coarsening_and_refinement() or load() via a
3829 * previously attached callback function (as the register_data_attach()
3830 * function does) because the classes that eventually want the data
3831 * back may need to do some setup between the point in time where the
3832 * mesh has been recreated and when the data can actually be received.
3833 * An example is the parallel::distributed::SolutionTransfer class
3834 * that can really only receive the data once not only the mesh is
3835 * completely available again on the current processor, but only
3836 * after a DoFHandler has been reinitialized and distributed
3837 * degrees of freedom. In other words, there is typically a significant
3838 * amount of set up that needs to happen in user space before the classes
3839 * that can receive data attached to cell are ready to actually do so.
3840 * When they are, they use the current function to tell the triangulation
3841 * object that now is the time when they are ready by calling the
3842 * current function.
3843 *
3844 * The supplied callback function is then called for each newly locally
3845 * owned cell. The first argument to the callback is an iterator that
3846 * designates the cell; the second argument indicates the status of the
3847 * cell in question; and the third argument localizes a memory area by
3848 * two iterators that contains the data that was previously saved from
3849 * the callback provided to register_data_attach().
3850 *
3851 * The CellStatus will indicate if the cell was refined, coarsened, or
3852 * persisted unchanged. The @p cell_iterator argument to the callback
3853 * will then either be an active,
3854 * locally owned cell (if the cell was not refined), or the immediate
3855 * parent if it was refined during execute_coarsening_and_refinement().
3856 * Therefore, contrary to during register_data_attach(), you can now
3857 * access the children if the status is `CellStatus::cell_will_be_refined` but
3858 * no longer for callbacks with status
3859 * `CellStatus::children_will_be_coarsened`.
3860 *
3861 * The first argument to this function, `handle`, corresponds to
3862 * the return value of register_data_attach(). (The precise
3863 * meaning of what the numeric value of this handle is supposed
3864 * to represent is neither important, nor should you try to use
3865 * it for anything other than transmit information between a
3866 * call to register_data_attach() to the corresponding call to
3867 * notify_ready_to_unpack().)
3868 */
3869 void
3870 notify_ready_to_unpack(
3871 const unsigned int handle,
3872 const std::function<
3873 void(const cell_iterator &,
3874 const ::dealii::CellStatus,
3875 const boost::iterator_range<std::vector<char>::const_iterator> &)>
3876 &unpack_callback);
3877
3878 internal::CellAttachedData<dim, spacedim> cell_attached_data;
3879
3880 protected:
3881 /**
3882 * Save additional cell-attached data from files all starting with
3883 * the base name given as last argument. The first
3884 * arguments are used to determine the offsets where to write buffers to.
3885 *
3886 * Called by @ref save.
3887 */
3888 void
3889 save_attached_data(const unsigned int global_first_cell,
3890 const unsigned int global_num_cells,
3891 const std::string &file_basename) const;
3892
3893 /**
3894 * Load additional cell-attached data files all starting with the
3895 * base name given as fourth argument, if any was saved.
3896 * The first arguments are used to determine the offsets where to read
3897 * buffers from.
3898 *
3899 * Called by @ref load.
3900 */
3901 void
3902 load_attached_data(const unsigned int global_first_cell,
3903 const unsigned int global_num_cells,
3904 const unsigned int local_num_cells,
3905 const std::string &file_basename,
3906 const unsigned int n_attached_deserialize_fixed,
3907 const unsigned int n_attached_deserialize_variable);
3908
3909 /**
3910 * A function to record the CellStatus of currently active cells.
3911 * This information is mandatory to transfer data between meshes
3912 * during adaptation or serialization, e.g., using SolutionTransfer.
3913 *
3914 * Relations will be stored in the private member local_cell_relations. For
3915 * an extensive description of CellStatus, see the documentation for the
3916 * member function register_data_attach().
3917 */
3918 void
3919 update_cell_relations();
3920
3921 /**
3922 * Function to pack data for
3923 * SolutionTransfer::prepare_for_coarsening_and_refinement() in the case of a
3924 * serial triangulation.
3925 */
3926 void
3927 pack_data_serial();
3928
3929
3930 /**
3931 * Function to unpack data for SolutionTransfer::interpolate() in the case of
3932 * a serial triangulation.
3933 */
3934 void
3935 unpack_data_serial();
3936
3937 /**
3938 * Vector of pairs, each containing a deal.II cell iterator and its
3939 * respective CellStatus. To update its contents, use the
3940 * update_cell_relations() member function.
3941 */
3942 std::vector<typename internal::CellAttachedDataSerializer<dim, spacedim>::
3943 cell_relation_t>
3944 local_cell_relations;
3945
3946 internal::CellAttachedDataSerializer<dim, spacedim> data_serializer;
3947 /**
3948 * @}
3949 */
3950
3951 public:
3952 /**
3953 * @name Exceptions
3954 * @{
3955 */
3956
3957 /**
3958 * Exception
3959 *
3960 * @ingroup Exceptions
3961 */
3962 DeclException2(ExcInvalidLevel,
3963 int,
3964 int,
3965 << "You are requesting information from refinement level "
3966 << arg1
3967 << " of a triangulation, but this triangulation only has "
3968 << arg2 << " refinement levels. The given level " << arg1
3969 << " must be *less* than " << arg2 << '.');
3970 /**
3971 * The function raising this exception can only operate on an empty
3972 * Triangulation, i.e., a Triangulation without grid cells.
3973 *
3974 * @ingroup Exceptions
3975 */
3976 DeclException2(
3977 ExcTriangulationNotEmpty,
3978 int,
3979 int,
3980 << "You are trying to perform an operation on a triangulation "
3981 << "that is only allowed if the triangulation is currently empty. "
3982 << "However, it currently stores " << arg1 << " vertices and has "
3983 << "cells on " << arg2 << " levels.");
3984 /**
3985 * Trying to re-read a grid, an error occurred.
3986 *
3987 * @ingroup Exceptions
3988 */
3989 DeclException0(ExcGridReadError);
3990 /**
3991 * Exception
3992 * @ingroup Exceptions
3993 */
3994 DeclException0(ExcFacesHaveNoLevel);
3995 /**
3996 * The triangulation level you accessed is empty.
3997 *
3998 * @ingroup Exceptions
3999 */
4000 DeclException1(ExcEmptyLevel,
4001 int,
4002 << "You tried to do something on level " << arg1
4003 << ", but this level is empty.");
4004
4005 /**
4006 * Exception
4007 *
4008 * Requested boundary_id not found
4009 *
4010 * @ingroup Exceptions
4011 */
4012 DeclException1(ExcBoundaryIdNotFound,
4013 types::boundary_id,
4014 << "The given boundary_id " << arg1
4015 << " is not defined in this Triangulation!");
4016
4017 /**
4018 * Exception
4019 *
4020 * @ingroup Exceptions
4021 */
4022 DeclExceptionMsg(
4023 ExcInconsistentCoarseningFlags,
4024 "A cell is flagged for coarsening, but either not all of its siblings "
4025 "are active or flagged for coarsening as well. Please clean up all "
4026 "coarsen flags on your triangulation via "
4027 "Triangulation::prepare_coarsening_and_refinement() beforehand!");
4028
4029 /** @} */
4030
4031 protected:
4032 /**
4033 * Do some smoothing in the process of refining the triangulation. See the
4034 * general doc of this class for more information about this.
4035 */
4036 MeshSmoothing smooth_grid;
4037
4038 /**
4039 * Vector caching all reference-cell types of the given triangulation
4040 * (also in the distributed case).
4041 */
4042 std::vector<ReferenceCell> reference_cells;
4043
4044 /**
4045 * Write a bool vector to the given stream, writing a pre- and a postfix
4046 * magic number. The vector is written in an almost binary format, i.e. the
4047 * bool flags are packed but the data is written as ASCII text.
4048 *
4049 * The flags are stored in a binary format: for each @p true, a @p 1 bit is
4050 * stored, a @p 0 bit otherwise. The bits are stored as <tt>unsigned
4051 * char</tt>, thus avoiding endianness. They are written to @p out in plain
4052 * text, thus amounting to 3.6 bits in the output per bits in the input on
4053 * the average. Other information (magic numbers and number of elements of
4054 * the input vector) is stored as plain text as well. The format should
4055 * therefore be interplatform compatible.
4056 */
4057 static void
4058 write_bool_vector(const unsigned int magic_number1,
4059 const std::vector<bool> &v,
4060 const unsigned int magic_number2,
4061 std::ostream &out);
4062
4063 /**
4064 * Re-read a vector of bools previously written by @p write_bool_vector and
4065 * compare with the magic numbers.
4066 */
4067 static void
4068 read_bool_vector(const unsigned int magic_number1,
4069 std::vector<bool> &v,
4070 const unsigned int magic_number2,
4071 std::istream &in);
4072
4073 /**
4074 * Recreate information about periodic neighbors from
4075 * periodic_face_pairs_level_0.
4076 */
4077 void
4078 update_periodic_face_map();
4079
4080 /**
4081 * Update the internal reference_cells vector.
4082 */
4083 virtual void
4084 update_reference_cells();
4085
4086
4087 private:
4088 /**
4089 * Policy with the Triangulation-specific tasks related to creation,
4090 * refinement, and coarsening.
4091 */
4092 std::unique_ptr<
4093 dealii::internal::TriangulationImplementation::Policy<dim, spacedim>>
4094 policy;
4095
4096 /**
4097 * If add_periodicity() is called, this variable stores the given periodic
4098 * face pairs on level 0 for later access during the identification of ghost
4099 * cells for the multigrid hierarchy and for setting up the
4100 * periodic_face_map.
4101 */
4102 std::vector<GridTools::PeriodicFacePair<cell_iterator>>
4103 periodic_face_pairs_level_0;
4104
4105 /**
4106 * If add_periodicity() is called, this variable stores the active periodic
4107 * face pairs.
4108 */
4109 std::map<std::pair<cell_iterator, unsigned int>,
4110 std::pair<std::pair<cell_iterator, unsigned int>,
4111 types::geometric_orientation>>
4112 periodic_face_map;
4113
4114 /**
4115 * Declare a number of iterator types for raw iterators, i.e., iterators
4116 * that also iterate over holes in the list of cells left by cells that have
4117 * been coarsened away in previous mesh refinement cycles.
4118 *
4119 * Since users should never have to access these internal properties of how
4120 * we store data, these iterator types are made private.
4121 */
4122 using raw_cell_iterator = TriaRawIterator<CellAccessor<dim, spacedim>>;
4123 using raw_face_iterator =
4124 TriaRawIterator<TriaAccessor<dim - 1, dim, spacedim>>;
4125 using raw_vertex_iterator =
4126 TriaRawIterator<dealii::TriaAccessor<0, dim, spacedim>>;
4127 using raw_line_iterator = typename IteratorSelector::raw_line_iterator;
4128 using raw_quad_iterator = typename IteratorSelector::raw_quad_iterator;
4129 using raw_hex_iterator = typename IteratorSelector::raw_hex_iterator;
4130
4131 /**
4132 * @name Cell iterator functions for internal use
4133 * @{
4134 */
4135
4136 /**
4137 * Iterator to the first cell, used or not, on level @p level. If a level
4138 * has no cells, a past-the-end iterator is returned.
4139 */
4140 raw_cell_iterator
4141 begin_raw(const unsigned int level = 0) const;
4142
4143 /**
4144 * Return a raw iterator which is the first iterator not on level. If @p
4145 * level is the last level, then this returns <tt>end()</tt>.
4146 */
4147 raw_cell_iterator
4148 end_raw(const unsigned int level) const;
4149
4150 /** @} */
4151
4152 /**
4153 * @name Line iterator functions for internal use
4154 * @{
4155 */
4156
4157 /**
4158 * Iterator to the first line, used or not, on level @p level. If a level
4159 * has no lines, a past-the-end iterator is returned. If lines are no
4160 * cells, i.e. for @p dim>1 no @p level argument must be given. The same
4161 * applies for all the other functions above, of course.
4162 */
4163 raw_line_iterator
4164 begin_raw_line(const unsigned int level = 0) const;
4165
4166 /**
4167 * Iterator to the first used line on level @p level.
4168 *
4169 * @note The given @p level argument needs to correspond to a level of the
4170 * triangulation, i.e., should be less than the value returned by
4171 * n_levels(). On the other hand, for parallel computations using
4172 * a parallel::distributed::Triangulation object, it is often convenient
4173 * to write loops over the cells of all levels of the global mesh, even
4174 * if the <i>local</i> portion of the triangulation does not actually
4175 * have cells at one of the higher levels. In those cases, the
4176 * @p level argument is accepted if it is less than what the
4177 * n_global_levels() function returns. If the given @p level is
4178 * between the values returned by n_levels() and n_global_levels(),
4179 * then no cells exist in the local portion of the triangulation
4180 * at this level, and the function simply returns what end() would
4181 * return.
4182 */
4183 line_iterator
4184 begin_line(const unsigned int level = 0) const;
4185
4186 /**
4187 * Iterator to the first active line on level @p level.
4188 *
4189 * @note The given @p level argument needs to correspond to a level of the
4190 * triangulation, i.e., should be less than the value returned by
4191 * n_levels(). On the other hand, for parallel computations using
4192 * a parallel::distributed::Triangulation object, it is often convenient
4193 * to write loops over the cells of all levels of the global mesh, even
4194 * if the <i>local</i> portion of the triangulation does not actually
4195 * have cells at one of the higher levels. In those cases, the
4196 * @p level argument is accepted if it is less than what the
4197 * n_global_levels() function returns. If the given @p level is
4198 * between the values returned by n_levels() and n_global_levels(),
4199 * then no cells exist in the local portion of the triangulation
4200 * at this level, and the function simply returns what end() would
4201 * return.
4202 */
4203 active_line_iterator
4204 begin_active_line(const unsigned int level = 0) const;
4205
4206 /**
4207 * Iterator past the end; this iterator serves for comparisons of iterators
4208 * with past-the-end or before-the-beginning states.
4209 */
4210 line_iterator
4211 end_line() const;
4212
4213 /** @} */
4214
4215 /**
4216 * @name Quad iterator functions for internal use
4217 * @{
4218 */
4219
4220 /**
4221 * Iterator to the first quad, used or not, on the given level. If a level
4222 * has no quads, a past-the-end iterator is returned. If quads are no
4223 * cells, i.e. for $dim>2$ no level argument must be given.
4224 *
4225 * @note The given @p level argument needs to correspond to a level of the
4226 * triangulation, i.e., should be less than the value returned by
4227 * n_levels(). On the other hand, for parallel computations using
4228 * a parallel::distributed::Triangulation object, it is often convenient
4229 * to write loops over the cells of all levels of the global mesh, even
4230 * if the <i>local</i> portion of the triangulation does not actually
4231 * have cells at one of the higher levels. In those cases, the
4232 * @p level argument is accepted if it is less than what the
4233 * n_global_levels() function returns. If the given @p level is
4234 * between the values returned by n_levels() and n_global_levels(),
4235 * then no cells exist in the local portion of the triangulation
4236 * at this level, and the function simply returns what end() would
4237 * return.
4238 */
4239 raw_quad_iterator
4240 begin_raw_quad(const unsigned int level = 0) const;
4241
4242 /**
4243 * Iterator to the first used quad on level @p level.
4244 *
4245 * @note The given @p level argument needs to correspond to a level of the
4246 * triangulation, i.e., should be less than the value returned by
4247 * n_levels(). On the other hand, for parallel computations using
4248 * a parallel::distributed::Triangulation object, it is often convenient
4249 * to write loops over the cells of all levels of the global mesh, even
4250 * if the <i>local</i> portion of the triangulation does not actually
4251 * have cells at one of the higher levels. In those cases, the
4252 * @p level argument is accepted if it is less than what the
4253 * n_global_levels() function returns. If the given @p level is
4254 * between the values returned by n_levels() and n_global_levels(),
4255 * then no cells exist in the local portion of the triangulation
4256 * at this level, and the function simply returns what end() would
4257 * return.
4258 */
4259 quad_iterator
4260 begin_quad(const unsigned int level = 0) const;
4261
4262 /**
4263 * Iterator to the first active quad on level @p level.
4264 *
4265 * @note The given @p level argument needs to correspond to a level of the
4266 * triangulation, i.e., should be less than the value returned by
4267 * n_levels(). On the other hand, for parallel computations using
4268 * a parallel::distributed::Triangulation object, it is often convenient
4269 * to write loops over the cells of all levels of the global mesh, even
4270 * if the <i>local</i> portion of the triangulation does not actually
4271 * have cells at one of the higher levels. In those cases, the
4272 * @p level argument is accepted if it is less than what the
4273 * n_global_levels() function returns. If the given @p level is
4274 * between the values returned by n_levels() and n_global_levels(),
4275 * then no cells exist in the local portion of the triangulation
4276 * at this level, and the function simply returns what end() would
4277 * return.
4278 */
4279 active_quad_iterator
4280 begin_active_quad(const unsigned int level = 0) const;
4281
4282 /**
4283 * Iterator past the end; this iterator serves for comparisons of iterators
4284 * with past-the-end or before-the-beginning states.
4285 */
4286 quad_iterator
4287 end_quad() const;
4288
4289 /** @} */
4290
4291 /**
4292 * @name Hex iterator functions for internal use
4293 * @{
4294 */
4295
4296 /**
4297 * Iterator to the first hex, used or not, on level @p level. If a level has
4298 * no hexes, a past-the-end iterator is returned.
4299 *
4300 * @note The given @p level argument needs to correspond to a level of the
4301 * triangulation, i.e., should be less than the value returned by
4302 * n_levels(). On the other hand, for parallel computations using
4303 * a parallel::distributed::Triangulation object, it is often convenient
4304 * to write loops over the cells of all levels of the global mesh, even
4305 * if the <i>local</i> portion of the triangulation does not actually
4306 * have cells at one of the higher levels. In those cases, the
4307 * @p level argument is accepted if it is less than what the
4308 * n_global_levels() function returns. If the given @p level is
4309 * between the values returned by n_levels() and n_global_levels(),
4310 * then no cells exist in the local portion of the triangulation
4311 * at this level, and the function simply returns what end() would
4312 * return.
4313 */
4314 raw_hex_iterator
4315 begin_raw_hex(const unsigned int level = 0) const;
4316
4317 /**
4318 * Iterator to the first used hex on level @p level.
4319 *
4320 * @note The given @p level argument needs to correspond to a level of the
4321 * triangulation, i.e., should be less than the value returned by
4322 * n_levels(). On the other hand, for parallel computations using
4323 * a parallel::distributed::Triangulation object, it is often convenient
4324 * to write loops over the cells of all levels of the global mesh, even
4325 * if the <i>local</i> portion of the triangulation does not actually
4326 * have cells at one of the higher levels. In those cases, the
4327 * @p level argument is accepted if it is less than what the
4328 * n_global_levels() function returns. If the given @p level is
4329 * between the values returned by n_levels() and n_global_levels(),
4330 * then no cells exist in the local portion of the triangulation
4331 * at this level, and the function simply returns what end() would
4332 * return.
4333 */
4334 hex_iterator
4335 begin_hex(const unsigned int level = 0) const;
4336
4337 /**
4338 * Iterator to the first active hex on level @p level.
4339 *
4340 * @note The given @p level argument needs to correspond to a level of the
4341 * triangulation, i.e., should be less than the value returned by
4342 * n_levels(). On the other hand, for parallel computations using
4343 * a parallel::distributed::Triangulation object, it is often convenient
4344 * to write loops over the cells of all levels of the global mesh, even
4345 * if the <i>local</i> portion of the triangulation does not actually
4346 * have cells at one of the higher levels. In those cases, the
4347 * @p level argument is accepted if it is less than what the
4348 * n_global_levels() function returns. If the given @p level is
4349 * between the values returned by n_levels() and n_global_levels(),
4350 * then no cells exist in the local portion of the triangulation
4351 * at this level, and the function simply returns what end() would
4352 * return.
4353 */
4354 active_hex_iterator
4355 begin_active_hex(const unsigned int level = 0) const;
4356
4357 /**
4358 * Iterator past the end; this iterator serves for comparisons of iterators
4359 * with past-the-end or before-the-beginning states.
4360 */
4361 hex_iterator
4362 end_hex() const;
4363
4364 /** @} */
4365
4366
4367 /**
4368 * The (public) function clear() will only work when the triangulation is
4369 * not subscribed to by other users. The clear_despite_subscriptions()
4370 * function now allows the triangulation being cleared even when there are
4371 * subscriptions.
4372 *
4373 * Make sure, you know what you do, when calling this function, as its use
4374 * is reasonable in very rare cases, only. For example, when the
4375 * subscriptions were for the initially empty Triangulation and the
4376 * Triangulation object wants to release its memory before throwing an
4377 * assertion due to input errors (e.g. in the create_triangulation()
4378 * function).
4379 */
4380 void
4381 clear_despite_subscriptions();
4382
4383 /**
4384 * Reset triangulation policy.
4385 */
4386 void
4387 reset_policy();
4388
4389 /**
4390 * For all cells, set the active cell indices so that active cells know the
4391 * how many-th active cell they are, and all other cells have an invalid
4392 * value. This function is called after mesh creation, refinement, and
4393 * serialization.
4394 */
4395 void
4396 reset_active_cell_indices();
4397
4398 /**
4399 * Reset global cell ids and global level cell ids.
4400 */
4401 void
4402 reset_global_cell_indices();
4403
4404 /**
4405 * Reset cache for the cells' vertex indices.
4406 */
4407 void
4408 reset_cell_vertex_indices_cache();
4409
4410 /**
4411 * Refine all cells on all levels which were previously flagged for
4412 * refinement.
4413 *
4414 * Note, that this function uses the <tt>line->user_flags</tt> for
4415 * <tt>dim=2,3</tt> and the <tt>quad->user_flags</tt> for <tt>dim=3</tt>.
4416 *
4417 * The function returns a list of cells that have produced children that
4418 * satisfy the criteria of
4419 * @ref GlossDistorted "distorted cells"
4420 * if the <code>check_for_distorted_cells</code> flag was specified upon
4421 * creation of this object, at
4422 */
4423 DistortedCellList
4424 execute_refinement();
4425
4426 /**
4427 * Coarsen all cells which were flagged for coarsening, or rather: delete
4428 * all children of those cells of which all child cells are flagged for
4429 * coarsening and several other constraints hold (see the general doc of
4430 * this class).
4431 */
4432 void
4433 execute_coarsening();
4434
4435 /**
4436 * Make sure that either all or none of the children of a cell are tagged
4437 * for coarsening.
4438 */
4439 void
4440 fix_coarsen_flags();
4441
4442 /**
4443 * Translate the unique id of a coarse cell to its index. See the glossary
4444 * entry on
4445 * @ref GlossCoarseCellId "coarse cell IDs"
4446 * for more information.
4447 *
4448 * @note For serial and shared triangulation both id and index are the same.
4449 * For distributed triangulations setting both might differ, since the
4450 * id might correspond to a global id and the index to a local id. If
4451 * a cell does not exist locally, the returned value is
4452 * numbers::invalid_unsigned_int.
4453 *
4454 * @param coarse_cell_id Unique id of the coarse cell.
4455 * @return Index of the coarse cell within the current triangulation.
4456 */
4457 virtual unsigned int
4458 coarse_cell_id_to_coarse_cell_index(
4459 const types::coarse_cell_id coarse_cell_id) const;
4460
4461
4462 /**
4463 * Translate the index of coarse cell to its unique id. See the glossary
4464 * entry on
4465 * @ref GlossCoarseCellId "coarse cell IDs"
4466 * for more information.
4467 *
4468 * @note See the note of the method
4469 * coarse_cell_id_to_coarse_cell_index().
4470 *
4471 * @param coarse_cell_index Index of the coarse cell.
4472 * @return Id of the coarse cell.
4473 */
4474 virtual types::coarse_cell_id
4475 coarse_cell_index_to_coarse_cell_id(
4476 const unsigned int coarse_cell_index) const;
4477
4478 /**
4479 * Array of pointers pointing to the objects storing the cell data on the
4480 * different levels.
4481 */
4482 std::vector<
4483 std::unique_ptr<dealii::internal::TriangulationImplementation::TriaLevel>>
4484 levels;
4485
4486 /**
4487 * Pointer to the faces of the triangulation. In 1d this contains nothing,
4488 * in 2d it contains data concerning lines and in 3d quads and lines. All
4489 * of these have no level and are therefore treated separately.
4490 */
4491 std::unique_ptr<dealii::internal::TriangulationImplementation::TriaFaces>
4492 faces;
4493
4494
4495 /**
4496 * Array of the vertices of this triangulation.
4497 */
4498 std::vector<Point<spacedim>> vertices;
4499
4500 /**
4501 * Array storing a bit-pattern which vertices are used.
4502 */
4503 std::vector<bool> vertices_used;
4504
4505 /**
4506 * Collection of Manifold objects.
4507 */
4508 std::map<types::manifold_id, std::unique_ptr<const Manifold<dim, spacedim>>>
4509 manifolds;
4510
4511 /**
4512 * Flag indicating whether anisotropic refinement took place.
4513 */
4514 bool anisotropic_refinement;
4515
4516
4517 /**
4518 * A flag that determines whether we are to check for distorted cells upon
4519 * creation and refinement of a mesh.
4520 */
4521 const bool check_for_distorted_cells;
4522
4523 /**
4524 * Cache to hold the numbers of lines, quads, hexes, etc. These numbers are
4525 * set at the end of the refinement and coarsening functions and enable
4526 * faster access later on. In the old days, whenever one wanted to access
4527 * one of these numbers, one had to perform a loop over all lines, e.g., and
4528 * count the elements until we hit the end iterator. This is time consuming
4529 * and since access to the number of lines etc is a rather frequent
4530 * operation, this was not an optimal solution.
4531 */
4532 dealii::internal::TriangulationImplementation::NumberCache<dim> number_cache;
4533
4534 /**
4535 * A map that relates the number of a boundary vertex to the boundary
4536 * indicator. This field is only used in 1d. We have this field because we
4537 * store boundary indicator information with faces in 2d and higher where we
4538 * have space in the structures that store data for faces, but in 1d there
4539 * is no such space for faces.
4540 *
4541 * The field is declared as a pointer for a rather mundane reason: all other
4542 * fields of this class that can be modified by the TriaAccessor hierarchy
4543 * are pointers, and so these accessor classes store a const pointer to the
4544 * triangulation. We could no longer do so for TriaAccessor<0,1,spacedim> if
4545 * this field (that can be modified by TriaAccessor::set_boundary_id) were
4546 * not a pointer.
4547 */
4548 std::unique_ptr<std::map<unsigned int, types::boundary_id>>
4549 vertex_to_boundary_id_map_1d;
4550
4551
4552 /**
4553 * A map that relates the number of a boundary vertex to the manifold
4554 * indicator. This field is only used in 1d. We have this field because we
4555 * store manifold indicator information with faces in 2d and higher where we
4556 * have space in the structures that store data for faces, but in 1d there
4557 * is no such space for faces.
4558 *
4559 * @note Manifold objects are pretty useless for points since they are
4560 * neither refined nor are their interiors mapped. We nevertheless allow
4561 * storing manifold ids for points to be consistent in dimension-independent
4562 * programs.
4563 *
4564 * The field is declared as a pointer for a rather mundane reason: all other
4565 * fields of this class that can be modified by the TriaAccessor hierarchy
4566 * are pointers, and so these accessor classes store a const pointer to the
4567 * triangulation. We could no longer do so for TriaAccessor<0,1,spacedim> if
4568 * this field (that can be modified by TriaAccessor::set_manifold_id) were
4569 * not a pointer.
4570 */
4571 std::unique_ptr<std::map<unsigned int, types::manifold_id>>
4572 vertex_to_manifold_id_map_1d;
4573
4574 // make a couple of classes friends
4575 template <int, int, int>
4576 friend class TriaAccessorBase;
4577 template <int, int, int>
4578 friend class TriaAccessor;
4579 friend class TriaAccessor<0, 1, spacedim>;
4580
4581 friend class CellAccessor<dim, spacedim>;
4582
4583 friend struct dealii::internal::TriaAccessorImplementation::Implementation;
4584
4585 friend struct dealii::internal::TriangulationImplementation::Implementation;
4586 friend struct dealii::internal::TriangulationImplementation::
4587 ImplementationMixedMesh;
4588
4589 friend class dealii::internal::TriangulationImplementation::TriaObjects;
4590
4591 // explicitly check for sensible template arguments, but not on windows
4592 // because MSVC creates bogus warnings during normal compilation
4593 #ifndef DEAL_II_MSVC
4594 static_assert(dim <= spacedim,
4595 "The dimension <dim> of a Triangulation must be less than or "
4596 "equal to the space dimension <spacedim> in which it lives.");
4597 #endif
4598 };
4599
4600
4601 #ifndef DOXYGEN
4602
4603
4604
4605 namespace internal
4606 {
4607 namespace TriangulationImplementation
4608 {
4609 template <class Archive>
4610 void
4611 NumberCache<1>::serialize(Archive &ar, const unsigned int)
4612 {
4613 ar &n_levels;
4614 ar &n_lines &n_lines_level;
4615 ar &n_active_lines &n_active_lines_level;
4616 }
4617
4618
4619 template <class Archive>
4620 void
4621 NumberCache<2>::serialize(Archive &ar, const unsigned int version)
4622 {
4623 this->NumberCache<1>::serialize(ar, version);
4624
4625 ar &n_quads &n_quads_level;
4626 ar &n_active_quads &n_active_quads_level;
4627 }
4628
4629
4630 template <class Archive>
4631 void
4632 NumberCache<3>::serialize(Archive &ar, const unsigned int version)
4633 {
4634 this->NumberCache<2>::serialize(ar, version);
4635
4636 ar &n_hexes &n_hexes_level;
4637 ar &n_active_hexes &n_active_hexes_level;
4638 }
4639
4640 } // namespace TriangulationImplementation
4641 } // namespace internal
4642
4643
4644 template <int dim, int spacedim>
4645 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4646 inline bool Triangulation<dim, spacedim>::vertex_used(
4647 const unsigned int index) const
4648 {
4649 AssertIndexRange(index, vertices_used.size());
4650 return vertices_used[index];
4651 }
4652
4653
4654
4655 template <int dim, int spacedim>
4656 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4657 inline unsigned int Triangulation<dim, spacedim>::n_levels() const
4658 {
4659 return number_cache.n_levels;
4660 }
4661
4662 template <int dim, int spacedim>
4663 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4664 inline unsigned int Triangulation<dim, spacedim>::n_global_levels() const
4665 {
4666 return number_cache.n_levels;
4667 }
4668
4669
4670 template <int dim, int spacedim>
4671 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4672 inline unsigned int Triangulation<dim, spacedim>::n_vertices() const
4673 {
4674 return vertices.size();
4675 }
4676
4677
4678
4679 template <int dim, int spacedim>
4680 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4681 inline const std::vector<Point<spacedim>>
4682 &Triangulation<dim, spacedim>::get_vertices() const
4683 {
4684 return vertices;
4685 }
4686
4687
4688 template <int dim, int spacedim>
4689 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4690 template <class Archive>
4691 void Triangulation<dim, spacedim>::save(Archive &ar, const unsigned int) const
4692 {
4693 // as discussed in the documentation, do not store the signals as
4694 // well as boundary and manifold description but everything else
4695 ar &smooth_grid;
4696
4697 unsigned int n_levels = levels.size();
4698 ar &n_levels;
4699 for (const auto &level : levels)
4700 ar &level;
4701
4702 // boost dereferences a nullptr when serializing a nullptr
4703 // at least up to 1.65.1. This causes problems with clang-5.
4704 // Therefore, work around it.
4705 bool faces_is_nullptr = (faces.get() == nullptr);
4706 ar &faces_is_nullptr;
4707 if (!faces_is_nullptr)
4708 ar &faces;
4709
4710 ar &vertices;
4711 ar &vertices_used;
4712
4713 ar &anisotropic_refinement;
4714 ar &number_cache;
4715
4716 ar &check_for_distorted_cells;
4717
4718 if (dim == 1)
4719 {
4720 ar &vertex_to_boundary_id_map_1d;
4721 ar &vertex_to_manifold_id_map_1d;
4722 }
4723 }
4724
4725
4726
4727 template <int dim, int spacedim>
4728 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4729 template <class Archive>
4730 void Triangulation<dim, spacedim>::load(Archive &ar, const unsigned int)
4731 {
4732 // clear previous content. this also calls the respective signal
4733 clear();
4734
4735 // as discussed in the documentation, do not store the signals as
4736 // well as boundary and manifold description but everything else
4737 ar &smooth_grid;
4738
4739 unsigned int size;
4740 ar &size;
4741 levels.resize(size);
4742 for (auto &level_ : levels)
4743 {
4744 std::unique_ptr<internal::TriangulationImplementation::TriaLevel> level;
4745 ar &level;
4746 level_ = std::move(level);
4747 }
4748
4749 // Workaround for nullptr, see in save().
4750 bool faces_is_nullptr = true;
4751 ar &faces_is_nullptr;
4752 if (!faces_is_nullptr)
4753 ar &faces;
4754
4755 ar &vertices;
4756 ar &vertices_used;
4757
4758 ar &anisotropic_refinement;
4759 ar &number_cache;
4760
4761 // the levels do not serialize the active_cell_indices because
4762 // they are easy enough to rebuild upon re-loading data. do
4763 // this here. don't forget to first resize the fields appropriately
4764 {
4765 for (const auto &level : levels)
4766 {
4767 level->active_cell_indices.resize(level->refine_flags.size());
4768 level->global_active_cell_indices.resize(level->refine_flags.size());
4769 level->global_level_cell_indices.resize(level->refine_flags.size());
4770 }
4771 reset_cell_vertex_indices_cache();
4772 reset_active_cell_indices();
4773 reset_global_cell_indices();
4774 }
4775
4776 reset_policy();
4777
4778 bool my_check_for_distorted_cells;
4779 ar &my_check_for_distorted_cells;
4780
4781 Assert(my_check_for_distorted_cells == check_for_distorted_cells,
4782 ExcMessage("The triangulation loaded into here must have the "
4783 "same setting with regard to reporting distorted "
4784 "cell as the one previously stored."));
4785
4786 if (dim == 1)
4787 {
4788 ar &vertex_to_boundary_id_map_1d;
4789 ar &vertex_to_manifold_id_map_1d;
4790 }
4791
4792 // trigger the create signal to indicate
4793 // that new content has been imported into
4794 // the triangulation
4795 signals.create();
4796 }
4797
4798
4799
4800 template <int dim, int spacedim>
4801 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4802 inline unsigned int Triangulation<dim, spacedim>::
4803 coarse_cell_id_to_coarse_cell_index(
4804 const types::coarse_cell_id coarse_cell_id) const
4805 {
4806 return coarse_cell_id;
4807 }
4808
4809
4810
4811 template <int dim, int spacedim>
4812 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
4813 inline types::coarse_cell_id
4814 Triangulation<dim, spacedim>::coarse_cell_index_to_coarse_cell_id(
4815 const unsigned int coarse_cell_index) const
4816 {
4817 return coarse_cell_index;
4818 }
4819
4820
4821
4822 /* -------------- declaration of explicit specializations ------------- */
4823
4824 template <>
4825 unsigned int
4826 Triangulation<1, 1>::n_quads() const;
4827 template <>
4828 unsigned int
4829 Triangulation<1, 1>::n_quads(const unsigned int level) const;
4830 template <>
4831 unsigned int
4832 Triangulation<1, 1>::n_raw_quads(const unsigned int level) const;
4833 template <>
4834 unsigned int
4835 Triangulation<2, 2>::n_raw_quads(const unsigned int level) const;
4836 template <>
4837 unsigned int
4838 Triangulation<3, 3>::n_raw_quads(const unsigned int level) const;
4839 template <>
4840 unsigned int
4841 Triangulation<3, 3>::n_raw_quads() const;
4842 template <>
4843 unsigned int
4844 Triangulation<1, 1>::n_active_quads(const unsigned int level) const;
4845 template <>
4846 unsigned int
4847 Triangulation<1, 1>::n_active_quads() const;
4848 template <>
4849 unsigned int
4850 Triangulation<1, 1>::n_raw_hexs(const unsigned int level) const;
4851 template <>
4852 unsigned int
4853 Triangulation<3, 3>::n_raw_hexs(const unsigned int level) const;
4854 template <>
4855 unsigned int
4856 Triangulation<3, 3>::n_hexs() const;
4857 template <>
4858 unsigned int
4859 Triangulation<3, 3>::n_active_hexs() const;
4860 template <>
4861 unsigned int
4862 Triangulation<3, 3>::n_active_hexs(const unsigned int) const;
4863 template <>
4864 unsigned int
4865 Triangulation<3, 3>::n_hexs(const unsigned int level) const;
4866
4867 template <>
4868 unsigned int
4869 Triangulation<1, 1>::max_adjacent_cells() const;
4870
4871
4872 // -------------------------------------------------------------------
4873 // -- Explicit specializations for codimension one grids
4874
4875
4876 template <>
4877 unsigned int
4878 Triangulation<1, 2>::n_quads() const;
4879 template <>
4880 unsigned int
4881 Triangulation<1, 2>::n_quads(const unsigned int level) const;
4882 template <>
4883 unsigned int
4884 Triangulation<1, 2>::n_raw_quads(const unsigned int level) const;
4885 template <>
4886 unsigned int
4887 Triangulation<2, 3>::n_raw_quads(const unsigned int level) const;
4888 template <>
4889 unsigned int
4890 Triangulation<1, 2>::n_raw_hexs(const unsigned int level) const;
4891 template <>
4892 unsigned int
4893 Triangulation<1, 2>::n_active_quads(const unsigned int level) const;
4894 template <>
4895 unsigned int
4896 Triangulation<1, 2>::n_active_quads() const;
4897 template <>
4898 unsigned int
4899 Triangulation<1, 2>::max_adjacent_cells() const;
4900
4901 // -------------------------------------------------------------------
4902 // -- Explicit specializations for codimension two grids
4903
4904 template <>
4905 unsigned int
4906 Triangulation<1, 3>::n_quads() const;
4907 template <>
4908 unsigned int
4909 Triangulation<1, 3>::n_quads(const unsigned int level) const;
4910 template <>
4911 unsigned int
4912 Triangulation<1, 3>::n_raw_quads(const unsigned int level) const;
4913 template <>
4914 unsigned int
4915 Triangulation<2, 3>::n_raw_quads(const unsigned int level) const;
4916 template <>
4917 unsigned int
4918 Triangulation<1, 3>::n_raw_hexs(const unsigned int level) const;
4919 template <>
4920 unsigned int
4921 Triangulation<1, 3>::n_active_quads(const unsigned int level) const;
4922 template <>
4923 unsigned int
4924 Triangulation<1, 3>::n_active_quads() const;
4925 template <>
4926 unsigned int
4927 Triangulation<1, 3>::max_adjacent_cells() const;
4928
4929 template <>
4930 bool
4931 Triangulation<1, 1>::prepare_coarsening_and_refinement();
4932 template <>
4933 bool
4934 Triangulation<1, 2>::prepare_coarsening_and_refinement();
4935 template <>
4936 bool
4937 Triangulation<1, 3>::prepare_coarsening_and_refinement();
4938
4939
4940 // Declare the existence of explicit instantiations of the class
4941 // above. This is not strictly necessary, but tells the compiler to
4942 // avoid instantiating templates that we know are instantiated in
4943 // .cc files and so can be referenced without implicit
4944 // instantiations.
4945 //
4946 // Unfortunately, this does not seem to work when building modules
4947 // because the compiler (well, Clang at least) then just doesn't
4948 // instantiate these classes at all, even though their members are
4949 // defined and explicitly instantiated in a .cc file.
4950 # ifndef DEAL_II_BUILDING_CXX20_MODULE
4951 extern template class Triangulation<1, 1>;
4952 extern template class Triangulation<1, 2>;
4953 extern template class Triangulation<1, 3>;
4954 extern template class Triangulation<2, 2>;
4955 extern template class Triangulation<2, 3>;
4956 extern template class Triangulation<3, 3>;
4957 # endif
4958
4959 #endif // DOXYGEN
4960
4961 DEAL_II_NAMESPACE_CLOSE
4962
4963 #endif