Debian Codegraph @

include/deal.II/grid/tria_levels.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_tria_levels_h
16 #define dealii_tria_levels_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/point.h>
22
23 #include <deal.II/grid/reference_cell.h>
24 #include <deal.II/grid/tria_objects.h>
25 #include <deal.II/grid/tria_objects_orientations.h>
26
27 #include <boost/serialization/utility.hpp>
28
29 #include <cstdint>
30 #include <vector>
31
32 DEAL_II_NAMESPACE_OPEN
33
34 namespace internal
35 {
36 namespace TriangulationImplementation
37 {
38 /**
39 * Store all information which belongs to one level of the multilevel
40 * hierarchy.
41 *
42 * In TriaLevel, all cell data is stored which is not dependent on the
43 * dimension, e.g. a field to store the refinement flag for the cells
44 * (what a cell actually is is declared elsewhere), etc. See also
45 * TriaObjects for non level-oriented data.
46 *
47 * There is another field, which may fit in here, namely the material data
48 * (for cells) or the boundary indicators (for faces), but since we need
49 * for a line or quad either boundary information or material data, we
50 * store them with the lines and quads rather than with the common data.
51 * Likewise, in 3d, we need boundary indicators for lines and quads (we
52 * need to know how to refine a line if the two adjacent faces have
53 * different boundary indicators), and material data for cells.
54 */
55 class TriaLevel
56 {
57 public:
58 /**
59 * Constructor.
60 *
61 * @param dim Dimension of the Triangulation.
62 */
63 TriaLevel(const unsigned int dim)
64 : dim(dim)
65 , cells(dim)
66 {}
67
68 /**
69 * Default constructor (needed by Boost).
70 */
71 TriaLevel()
72 : dim(numbers::invalid_unsigned_int)
73 , cells(numbers::invalid_unsigned_int)
74 {}
75
76 /**
77 * Dimension of the Triangulation.
78 */
79 unsigned int dim;
80
81 /**
82 * @p RefinementCase<dim>::Type flags for the cells to be refined with
83 * or not (RefinementCase<dim>::no_refinement). The meaning what a cell
84 * is, is dimension specific, therefore also the length of this vector
85 * depends on the dimension: in one dimension, the length of this vector
86 * equals the length of the @p lines vector, in two dimensions that of
87 * the @p quads vector, etc.
88 */
89 std::vector<std::uint8_t> refine_flags;
90
91 /**
92 * @p IsotropicRefinementChoices direction for the tetrahedral cells to be
93 * refined with
94 * or choose the optimal way @p ReferenceCell::isotropic_refinement.
95 */
96 std::vector<std::uint8_t> refine_choice;
97
98 /**
99 * Same meaning as the one above, but specifies whether a cell must be
100 * coarsened.
101 */
102 std::vector<bool> coarsen_flags;
103
104
105 /**
106 * An integer that, for every active cell, stores the how many-th active
107 * cell this is. For non-active cells, this value is unused and set to
108 * an invalid value.
109 */
110 std::vector<unsigned int> active_cell_indices;
111
112 /**
113 * Global cell index of each active cell.
114 */
115 std::vector<types::global_cell_index> global_active_cell_indices;
116
117 /**
118 * Global cell index of each cell on the given level.
119 */
120 std::vector<types::global_cell_index> global_level_cell_indices;
121
122 /**
123 * Levels and indices of the neighbors of the cells. Convention is, that
124 * the neighbors of the cell with index @p i are stored in the fields
125 * following $i*(2*real\_space\_dimension)$, e.g. in one spatial
126 * dimension, the neighbors of cell 0 are stored in
127 * <tt>neighbors[0]</tt> and <tt>neighbors[1]</tt>, the neighbors of
128 * cell 1 are stored in <tt>neighbors[2]</tt> and <tt>neighbors[3]</tt>,
129 * and so on.
130 *
131 * In neighbors, <tt>neighbors[i].first</tt> is the level, while
132 * <tt>neighbors[i].second</tt> is the index of the neighbor.
133 *
134 * If a neighbor does not exist (cell is at the boundary),
135 * <tt>level=index=-1</tt> is set.
136 *
137 * <em>Conventions:</em> The @p ith neighbor of a cell is the one which
138 * shares the @p ith face (@p Line in 2d, @p Quad in 3d) of this cell.
139 *
140 * The neighbor of a cell has at most the same level as this cell, i.e.
141 * it may or may not be refined.
142 *
143 * In one dimension, a neighbor may have any level less or equal the
144 * level of this cell. If it has the same level, it may be refined an
145 * arbitrary number of times, but the neighbor pointer still points to
146 * the cell on the same level, while the neighbors of the children of
147 * the neighbor may point to this cell or its children.
148 *
149 * In two and more dimensions, the neighbor is either on the same level
150 * and refined (in which case its children have neighbor pointers to
151 * this cell or its direct children), unrefined on the same level or one
152 * level down (in which case its neighbor pointer points to the parent
153 * cell of this cell).
154 */
155 std::vector<std::pair<int, int>> neighbors;
156
157 /**
158 * One integer per cell to store which subdomain it belongs to. This
159 * field is most often used in parallel computations, where it denotes
160 * which processor shall work on/owns the cells with a given subdomain
161 * number.
162 *
163 * This number is only used on active cells.
164 */
165 std::vector<types::subdomain_id> subdomain_ids;
166
167 /**
168 * The subdomain id used on each level for parallel multigrid.
169 *
170 * In contrast to the subdomain_id, this number is also used on inactive
171 * cells once the mesh has been partitioned also on the lower levels of
172 * the multigrid hierarchy.
173 */
174 std::vector<types::subdomain_id> level_subdomain_ids;
175
176 /**
177 * One integer for every consecutive pair of cells to store which index
178 * their parent has.
179 *
180 * (We store this information once for each pair of cells since every
181 * refinement, isotropic or anisotropic, and in any space dimension,
182 * always creates children in multiples of two, so there is no need to
183 * store the parent index for every cell.)
184 */
185 std::vector<int> parents;
186
187 /**
188 * One bool per cell to indicate the direction of the normal true: use
189 * orientation from vertex false: revert the orientation. See
190 * @ref GlossDirectionFlag.
191 *
192 * This is only used for codim==1 meshes.
193 */
194 std::vector<bool> direction_flags;
195
196 /**
197 * The object containing the data on lines and related functions
198 */
199 TriaObjects cells;
200
201 /**
202 * For edges, we enforce a standard convention that opposite
203 * edges should be parallel. Now, that's enforceable in most
204 * cases, and we have code that makes sure that if a mesh allows
205 * this to happen, that we have this convention. We also know
206 * that it is always possible to have opposite faces have
207 * parallel normal vectors. (For both things, see the paper by
208 * Agelek, Anderson, Bangerth, Barth in the ACM Transactions on
209 * Mathematical Software mentioned in the documentation of the
210 * GridTools::consistently_order_cells() function.)
211 *
212 * The problem is that we originally had another condition, namely that
213 * faces 0, 2 and 4 have normals that point into the cell, while the
214 * other faces have normals that point outward. It turns out that this
215 * is not always possible. In effect, we have to store whether the
216 * normal vector of each face of each cell follows this convention or
217 * not. If this is so, then this variable stores a @p true value,
218 * otherwise a @p false value.
219 *
220 * In effect, this field has <code>6*n_cells</code> elements, being the
221 * number of cells times the six faces each has.
222 *
223 * @note This array is only used in dim == 2 or dim == 3: for dim == 1
224 * meshes consist purely of lines which are always consistently oriented.
225 */
226 TriaObjectsOrientations face_orientations;
227
228 /**
229 * Reference cell type of each cell.
230 *
231 * @note Used only for dim=2 and dim=3.
232 */
233 std::vector<ReferenceCell> reference_cell;
234
235 /**
236 * A cache for the vertex indices of the cells (`structdim == dim`), in
237 * order to more quickly retrieve these frequently accessed quantities.
238 * For simplified addressing, the information is indexed by the maximum
239 * number of vertices possible for a cell (quadrilateral/hexahedron).
240 */
241 std::vector<unsigned int> cell_vertex_indices_cache;
242
243 /**
244 * Determine an estimate for the memory consumption (in bytes) of this
245 * object.
246 */
247 std::size_t
248 memory_consumption() const;
249
250 /**
251 * Read or write the data of this object to or from a stream for the
252 * purpose of serialization using the [BOOST serialization
253 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
254 */
255 template <class Archive>
256 void
257 serialize(Archive &ar, const unsigned int version);
258 };
259
260
261 template <class Archive>
262 void
263 TriaLevel::serialize(Archive &ar, const unsigned int)
264 {
265 ar &dim;
266
267 ar &refine_flags &coarsen_flags;
268
269 // do not serialize `active_cell_indices` and `vertex_indices_cache`
270 // here. instead of storing them to the stream and re-reading them again
271 // later, we just rebuild them in Triangulation::load()
272
273 ar &neighbors;
274 ar &subdomain_ids;
275 ar &level_subdomain_ids;
276 ar &parents;
277 ar &direction_flags;
278 ar &cells;
279 ar &face_orientations;
280 ar &reference_cell;
281 }
282
283 } // namespace TriangulationImplementation
284 } // namespace internal
285
286 DEAL_II_NAMESPACE_CLOSE
287
288 #endif