Debian Codegraph @

include/deal.II/grid/cell_data.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_grid_cell_data_h
16 #define dealii_grid_cell_data_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/types.h>
21
22 #include <deal.II/grid/reference_cell.h>
23
24 #include <vector>
25
26 DEAL_II_NAMESPACE_OPEN
27
28 /**
29 * The CellData class (and the related SubCellData class) is used to
30 * provide a comprehensive, but minimal, description of the cells when
31 * creating a triangulation via Triangulation::create_triangulation().
32 * Specifically, each CellData object -- describing one cell in a
33 * triangulation -- has member variables for indices of the $2^d$ vertices
34 * (the actual coordinates of the vertices are described in a separate
35 * vector passed to Triangulation::create_triangulation(), so the CellData
36 * object only needs to store indices into that vector), the material
37 * id of the cell that can be used in applications to describe which
38 * part of the domain a cell belongs to (see
39 * @ref GlossMaterialId "the glossary entry on material ids"),
40 * and a manifold id that is used to describe the geometry object
41 * that is responsible for this cell (see
42 * @ref GlossManifoldIndicator "the glossary entry on manifold ids")
43 * to describe the manifold this object belongs to.
44 *
45 * This structure is also used to represent data for faces and edges when used
46 * as a member of the SubCellData class. In this case, the template argument
47 * @p structdim of an object will be less than the dimension @p dim of the
48 * triangulation. If this is so, then #vertices array represents the indices of
49 * the vertices of one face or edge of one of the cells passed to
50 * Triangulation::create_triangulation(). Furthermore, for faces the
51 * material id has no meaning, and the @p material_id field is reused
52 * to store a @p boundary_id instead to designate which part of the boundary
53 * the face or edge belongs to (see
54 * @ref GlossBoundaryIndicator "the glossary entry on boundary ids").
55 *
56 * An example showing how this class can be used is in the
57 * <code>create_coarse_grid()</code> function of step-14. There are also
58 * many more use cases in the implementation of the functions of the
59 * GridGenerator namespace.
60 *
61 * @ingroup grid
62 */
63 template <int structdim>
64 struct CellData
65 {
66 /**
67 * Indices of the vertices of this cell. These indices correspond
68 * to entries in the vector of vertex locations passed to
69 * Triangulation::create_triangulation().
70 *
71 * By default, the constructor of this class initializes this variable to
72 * have as many entries as it takes to describe a hypercube cell (i.e., a
73 * ReferenceCells::Line, ReferenceCells::Quadrilateral, or
74 * ReferenceCells::Hexahedron). This is historical and dates back to the time
75 * where deal.II could only deal with these kinds of cells. If you want an
76 * object of the current type to describe, for example, a triangle or
77 * tetrahedron, then you either have to call this constructor with an explicit
78 * argument different from the default value, or manually resize the
79 * `vertices` member variable after construction.
80 *
81 * The kind of cell described by the current object is then determined by
82 * calling ReferenceCell::n_vertices_to_type() on the number of vertices
83 * described by this array.
84 */
85 std::vector<unsigned int> vertices;
86
87 /**
88 * Material or boundary indicator of this cell.
89 * This field is a union that stores <i>either</i> a boundary or
90 * a material id, depending on whether the current object is used
91 * to describe a cell (in a vector of CellData objects) or a
92 * face or edge (as part of a SubCellData object).
93 */
94 union
95 {
96 /**
97 * The material id of the cell being described. See the documentation
98 * of the CellData class for examples of how to use this field.
99 *
100 * This variable can only be used if the current object is used to
101 * describe a cell, i.e., if @p structdim equals the dimension
102 * @p dim of a triangulation.
103 */
104 types::material_id material_id;
105
106 /**
107 * The boundary id of a face or edge being described. See the documentation
108 * of the CellData class for examples of how to use this field.
109 *
110 * This variable can only be used if the current object is used to
111 * describe a face or edge, i.e., if @p structdim is less than the dimension
112 * @p dim of a triangulation. In this case, the CellData object this
113 * variable belongs to will be part of a SubCellData object.
114 */
115 types::boundary_id boundary_id;
116 };
117
118 /**
119 * Manifold identifier of this object. This identifier should be used to
120 * identify the manifold to which this object belongs, and from which this
121 * object will collect information on how to add points upon refinement.
122 *
123 * See the documentation of the CellData class for examples of how to use
124 * this field.
125 */
126 types::manifold_id manifold_id;
127
128 /**
129 * Default constructor. Sets the member variables to the following values:
130 *
131 * - vertex indices to invalid values
132 * - boundary or material id zero (the default for boundary or material ids)
133 * - manifold id to numbers::flat_manifold_id.
134 *
135 * By default, the constructor initializes the `vertices` member variable to
136 * have as many entries as it takes to describe a hypercube cell (i.e., a
137 * ReferenceCells::Line, ReferenceCells::Quadrilateral, or
138 * ReferenceCells::Hexahedron). This is historical and dates back to the time
139 * where deal.II could only deal with these kinds of cells. If you want an
140 * object of the current type to describe, for example, a triangle or
141 * tetrahedron, then you either have to call this constructor with an explicit
142 * argument different from the default value, or manually resize the
143 * `vertices` member variable after construction.
144 */
145 CellData(const unsigned int n_vertices =
146 ReferenceCells::get_hypercube<structdim>().n_vertices());
147
148 /**
149 * Comparison operator.
150 */
151 bool
152 operator==(const CellData<structdim> &other) const;
153
154 /**
155 * Read or write the data of this object to or from a stream for the
156 * purpose of serialization using the [BOOST serialization
157 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
158 */
159 template <class Archive>
160 void
161 serialize(Archive &ar, const unsigned int version);
162
163 static_assert(structdim > 0,
164 "The class CellData can only be used for structdim>0.");
165 };
166
167
168
169 /**
170 * The SubCellData class is used to describe information about faces and
171 * edges at the boundary of a mesh when creating a triangulation via
172 * Triangulation::create_triangulation(). It contains member variables
173 * that describe boundary edges and boundary quads.
174 *
175 * The class has no template argument and is used both in the description
176 * of boundary edges in 2d (in which case the contents of the
177 * @p boundary_quads member variable are ignored), as well as in the
178 * description of boundary edges and faces in 3d (in which case both the
179 * @p boundary_lines and @p boundary_quads members may be used). It is also
180 * used as the argument to Triangulation::create_triangulation() in 1d,
181 * where the contents of objects of the current type are simply ignored.
182 *
183 * By default, Triangulation::create_triangulation() simply assigns
184 * default boundary indicators and manifold indicators to edges and
185 * quads at the boundary of the mesh. (See the glossary entries on
186 * @ref GlossBoundaryIndicator "boundary ids"
187 * and
188 * @ref GlossManifoldIndicator "manifold ids"
189 * for more information on what they represent.) As a consequence,
190 * it is not <i>necessary</i> to explicitly describe the properties
191 * of boundary objects. In all cases, these properties can also be
192 * set at a later time, once the triangulation has already been
193 * created. On the other hand, it is sometimes convenient to describe
194 * boundary indicators or manifold ids at the time of creation. In
195 * these cases, the current class can be used by filling the
196 * @p boundary_lines and @p boundary_quads vectors with
197 * CellData<1> and CellData<2> objects that correspond to boundary
198 * edges and quads for which properties other than the default
199 * values should be used.
200 *
201 * Each entry in the @p boundary_lines and @p boundary_quads vectors
202 * then needs to correspond to an edge or quad of the cells that
203 * are described by the vector of CellData objects passed to
204 * Triangulation::create_triangulation(). I.e., the vertex indices
205 * stored in each entry need to correspond to an edge or face
206 * of the triangulation that has the same set of vertex indices,
207 * and in the same order. For these boundary edges or quads, one can
208 * then set either or both the CellData::boundary_id and
209 * CellData::manifold_id.
210 *
211 * There are also use cases where one may want to set the manifold id
212 * of an <i>interior</i> edge or face. Such faces, identified by
213 * their vertex indices, may also appear in the
214 * @p boundary_lines and @p boundary_quads vectors (despite the names of
215 * these member variables). However, it is then obviously not allowed
216 * to set a boundary id (because the object is not actually part of
217 * the boundary). As a consequence, to be valid, the CellData::boundary_id
218 * of interior edges or faces needs to equal
219 * numbers::internal_face_boundary_id.
220 *
221 * @ingroup grid
222 */
223 struct SubCellData
224 {
225 /**
226 * A vector of CellData<1> objects that describe boundary and manifold
227 * information for edges of 2d or 3d triangulations. For 2d triangulations,
228 * edges (lines) are of course the faces of the cells.
229 *
230 * This vector must not be used in the creation of 1d triangulations.
231 */
232 std::vector<CellData<1>> boundary_lines;
233
234 /**
235 * A vector of CellData<2> objects that describe boundary and manifold
236 * information for triangles and quads of 3d triangulations. The name of
237 * the variable is historical and dates back to a time when deal.II only
238 * supported hexahedral meshes in 3d, where then all boundary faces were
239 * necessarily quadrilaterals. However, the variable is now also used to
240 * describe boundary triangles for tetrahedral and mixed meshes.
241 *
242 * Whether an element in this array describes a boundary triangle or a
243 * boundary quad is determined by how many elements the `vertices`
244 * member variable of `CellData<2>` stores.
245 *
246 * This vector must not be used in the creation of 1d or 2d triangulations.
247 */
248 std::vector<CellData<2>> boundary_quads;
249
250 /**
251 * Determine whether the member variables above which may not be used in a
252 * given dimension are really empty. In other words, this function returns
253 * whether
254 * both @p boundary_lines and @p boundary_quads are empty vectors
255 * when @p dim equals one, and whether the @p boundary_quads
256 * vector is empty when @p dim equals two.
257 */
258 bool
259 check_consistency(const unsigned int dim) const;
260 };
261
262
263 template <int structdim>
264 template <class Archive>
265 void
266 CellData<structdim>::serialize(Archive &ar, const unsigned int /*version*/)
267 {
268 ar &vertices;
269 ar &material_id;
270 ar &boundary_id;
271 ar &manifold_id;
272 }
273
274 DEAL_II_NAMESPACE_CLOSE
275
276 #endif