Debian Codegraph @

include/deal.II/grid/grid_generator.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_generator_h
16 #define dealii_grid_generator_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/function.h>
23 #include <deal.II/base/point.h>
24 #include <deal.II/base/table.h>
25
26 #include <deal.II/cgal/additional_data.h>
27
28 #include <deal.II/grid/reference_cell.h>
29 #include <deal.II/grid/tria.h>
30
31 #include <array>
32 #include <limits>
33 #include <map>
34 #include <set>
35
36
37 DEAL_II_NAMESPACE_OPEN
38
39 #ifndef DOXYGEN
40 class ParameterHandler;
41 #endif
42
43 /**
44 * This namespace provides a collection of functions for generating
45 * triangulations for some basic geometries.
46 *
47 * Some of these functions receive a flag @p colorize (see
48 * @ref GlossColorization "the glossary entry on colorization").
49 * If this is set, parts of the boundary receive different
50 * @ref GlossBoundaryIndicator "boundary indicators"
51 * allowing them to be distinguished for the purpose of evaluating
52 * different boundary conditions.
53 *
54 * If the domain is curved, each of the domain parts that should be
55 * refined by following an appropriate Manifold description will
56 * receive a different
57 * @ref GlossManifoldIndicator "manifold indicator",
58 * and the correct Manifold descriptor will be attached to
59 * the Triangulation. Notice that if you later transform the
60 * triangulation, you have to make sure you attach the correct new Manifold
61 * to the triangulation.
62 *
63 * @ingroup grid
64 */
65 namespace GridGenerator
66 {
67 /**
68 * @name Creating meshes for basic geometries
69 */
70 /** @{ */
71
72 /**
73 * Initialize the given triangulation with a hypercube (line in 1d, square
74 * in 2d, etc) consisting of exactly one cell. The hypercube volume is the
75 * tensor product interval $[left,right]^{\text{dim}}$ in the present number
76 * of dimensions, where the limits are given as arguments. They default to
77 * zero and unity, then producing the unit hypercube.
78 *
79 * If the argument @p colorize is false, then all boundary indicators are
80 * set to zero (the default boundary indicator) for 2d and 3d. If it is
81 * true, the boundary is
82 * @ref GlossColorization "colorized"
83 * as in hyper_rectangle(). In 1d the
84 * indicators are always colorized, see hyper_rectangle().
85 *
86 * @image html hyper_cubes.png
87 *
88 * If @p dim < @p spacedim, this will create a @p dim dimensional object in
89 * the first @p dim coordinate directions embedded into the @p spacedim
90 * dimensional space with the remaining entries set to zero. For example, a
91 * <tt>Triangulation@<2,3@></tt> will be a square in the xy plane with z=0.
92 *
93 * See also subdivided_hyper_cube() for a coarse mesh consisting of several
94 * cells. See hyper_rectangle(), if different lengths in different ordinate
95 * directions are required.
96 *
97 * @pre The triangulation passed as argument needs to be empty when calling
98 * this function.
99 *
100 * @note This function is available through the python interface as
101 * `triangulation.generate_hyper_cube(left = 0., right = 1., colorize =
102 * false)`.
103 */
104 template <int dim, int spacedim>
105 void
106 hyper_cube(Triangulation<dim, spacedim> &tria,
107 const double left = 0.,
108 const double right = 1.,
109 const bool colorize = false);
110
111 /**
112 * Create a $d$-<a href="https://en.wikipedia.org/wiki/Simplex">simplex</a>
113 * (i.e., a triangle in 2d, or a tetrahedron in 3d) with
114 * $d+1$ corners. Since this function dates back to a time when deal.II
115 * did not support triangular and tetrahedral cells (which it does now),
116 * the simplex created by this function and described by the input arguments
117 * is subdivided into quadrilaterals and hexahedra by adding edge,
118 * face, and simplex midpoints, resulting in a mesh that consists of
119 * $d+1$ quadrilateral or hexahedral cells. (However, you can create a
120 * simplex geometry with a single simplex cell -- i.e., a triangle or
121 * a tetrahedron -- with both the GridGenerator::reference_cell() and
122 * directly with the Triangulation::create_triangulation() functions.)
123 *
124 * The @p vertices argument contains a vector with all d+1 vertices defining
125 * the corners of the simplex. They must be given in an order such that the
126 * vectors from the first vertex to each of the others form a right-handed
127 * system.
128 *
129 * The meshes generated in two and three dimensions are:
130 *
131 * @image html simplex_2d.png
132 * @image html simplex_3d.png
133 *
134 * @param tria The triangulation to be created. It needs to be empty upon
135 * calling this function.
136 *
137 * @param vertices The dim+1 corners of the simplex.
138 *
139 * @note Implemented for <tt>Triangulation@<2,2@></tt>,
140 * <tt>Triangulation@<3,3@></tt>.
141 *
142 * @note This function is available through the python interface as
143 * `triangulation.generate_simplex(vertices)`.
144 */
145 template <int dim>
146 void
147 simplex(Triangulation<dim, dim> &tria,
148 const std::vector<Point<dim>> &vertices);
149
150 /**
151 * Create a (coarse) grid with a single cell of the shape of the provided
152 * reference cell. This is a generalization of the hyper_cube() and simplex()
153 * functions above.
154 */
155 template <int dim, int spacedim>
156 void
157 reference_cell(Triangulation<dim, spacedim> &tria,
158 const ReferenceCell &reference_cell);
159
160
161 /**
162 * Same as hyper_cube(), but with the difference that not only one cell is
163 * created but each coordinate direction is subdivided into @p repetitions
164 * cells. Thus, the number of cells filling the given volume is
165 * <tt>repetitions<sup>dim</sup></tt>.
166 *
167 * If @p dim < @p spacedim, this will create a @p dim dimensional object in
168 * the first @p dim coordinate directions embedded into the @p spacedim
169 * dimensional space with the remaining entries set to zero. For example, a
170 * <tt>Triangulation@<2,3@></tt> will be a square in the xy plane with z=0.
171 *
172 * @pre The triangulation passed as argument needs to be empty when calling
173 * this function.
174 *
175 * @param tria The triangulation to create. It needs to be empty upon
176 * calling this function.
177 *
178 * @param repetitions An unsigned integer denoting the number of cells to
179 * generate in each direction.
180 *
181 * @param left Lower bound for the interval used to create the hyper cube.
182 *
183 * @param right Upper bound for the interval used to create the hyper cube.
184 *
185 * @param colorize Assign different boundary ids if set to true.
186 *
187 * @note This function is available through the python interface as
188 * `triangulation.generate_subdivided_hyper_cube(left = 0., right = 1.)`.
189 */
190 template <int dim, int spacedim>
191 void
192 subdivided_hyper_cube(Triangulation<dim, spacedim> &tria,
193 const unsigned int repetitions,
194 const double left = 0.,
195 const double right = 1.,
196 const bool colorize = false);
197
198 /**
199 * Create a coordinate-parallel brick from the two diagonally opposite
200 * corner points @p p1 and @p p2.
201 *
202 * If the @p colorize flag is <code>true</code>, then the @p boundary_ids of
203 * the boundary faces are assigned, such that the lower one in @p
204 * x-direction is 0, the upper one is 1. The indicators for the surfaces in
205 * @p y-direction are 2 and 3, the ones for @p z are 4 and 5. This
206 * corresponds to the numbers of faces of the unit square of cube as laid
207 * out in the documentation of the GeometryInfo class; see also
208 * @ref GlossColorization "the glossary entry on colorization".
209 * Importantly,
210 * however, in 3d
211 * @ref GlossColorization "colorization"
212 * does not set @p
213 * boundary_ids of <i>edges</i>, but only of <i>faces</i>, because each
214 * boundary edge is shared between two faces and it is not clear how the
215 * boundary id of an edge should be set in that case.
216 *
217 * Additionally, if @p colorize is @p true, material ids are assigned to the
218 * cells according to the octant their center is in: being in the right half
219 * space for any coordinate direction <i>x<sub>i</sub></i> adds
220 * 2<sup>i</sup>. For instance, a cell with center point (1,-1,1) yields a
221 * material id 5, assuming that the center of the hyper rectangle lies at
222 * the origin. No manifold id is set for the cells.
223 *
224 * If @p dim < @p spacedim, this will create a @p dim dimensional object in
225 * the first @p dim coordinate directions embedded into the @p spacedim
226 * dimensional space with the remaining entries set to zero. For example, a
227 * <tt>Triangulation@<2,3@></tt> will be a rectangle in the xy plane with
228 * z=0, defined by the two opposing corners @p p1 and @p p2.
229 *
230 * @pre The triangulation passed as argument needs to be empty when calling
231 * this function.
232 *
233 * @note This function is available through the python interface as
234 * `triangulation.generate_hyper_rectangle(p1, p2, colorize = false)`.
235 */
236 template <int dim, int spacedim>
237 void
238 hyper_rectangle(Triangulation<dim, spacedim> &tria,
239 const Point<dim> &p1,
240 const Point<dim> &p2,
241 const bool colorize = false);
242
243 /**
244 * Create a coordinate-parallel brick from the two diagonally opposite
245 * corner points @p p1 and @p p2. The number of cells in coordinate
246 * direction @p i is given by the integer <tt>repetitions[i]</tt>.
247 *
248 * To get cells with an aspect ratio different from that of the domain, use
249 * different numbers of subdivisions, given by @p repetitions, in different
250 * coordinate directions. The minimum number of subdivisions in each
251 * direction is 1.
252 *
253 * If the @p colorize flag is <code>true</code>, then the @p boundary_ids of
254 * the surfaces are assigned, such that the lower one in @p x-direction is
255 * 0, the upper one is 1 (the left and the right vertical face). The
256 * indicators for the surfaces in @p y-direction are 2 and 3, the ones for
257 * @p z are 4 and 5. Additionally, material ids are assigned to the cells
258 * according to the octant their center is in: being in the right half plane
259 * for any coordinate direction <i>x<sub>i</sub></i> adds 2<sup>i</sup> (see
260 * @ref GlossColorization "the glossary entry on colorization").
261 * For
262 * instance, the center point (1,-1,1) yields a material id 5 (this means
263 * that in 2d only material ids 0,1,2,3 are assigned independent from the
264 * number of repetitions).
265 *
266 * Note that the @p colorize flag is ignored in 1d and is assumed to always
267 * be true. That means the boundary indicator is 0 on the left and 1 on the
268 * right. See step-15 for details.
269 *
270 * If @p dim < @p spacedim, this will create a @p dim dimensional object in
271 * the first @p dim coordinate directions embedded into the @p spacedim
272 * dimensional space with the remaining entries set to zero. For example, a
273 * <tt>Triangulation@<2,3@></tt> will be a rectangle in the xy plane with
274 * z=0, defined by the two opposing corners @p p1 and @p p2.
275 *
276 * @note For an example of the use of this function see the step-28 tutorial
277 * program.
278 *
279 * @param tria The triangulation to be created. It needs to be empty upon
280 * calling this function.
281 *
282 * @param repetitions A vector of @p dim positive values denoting the number
283 * of cells to generate in that direction.
284 *
285 * @param p1 First corner point.
286 *
287 * @param p2 Second corner opposite to @p p1.
288 *
289 * @param colorize Assign different boundary ids if set to true. The same
290 * comments apply as for the hyper_rectangle() function.
291 *
292 * @note This function is available through the python interface as
293 * `triangulation.generate_subdivided_hyper_rectangle(repetitions, p1, p2,
294 * colorize = false)`.
295 */
296 template <int dim, int spacedim>
297 void
298 subdivided_hyper_rectangle(Triangulation<dim, spacedim> &tria,
299 const std::vector<unsigned int> &repetitions,
300 const Point<dim> &p1,
301 const Point<dim> &p2,
302 const bool colorize = false);
303
304 /**
305 * Like the previous function. However, here the second argument does not
306 * denote the number of subdivisions in each coordinate direction, but a
307 * sequence of step sizes for each coordinate direction. The domain will
308 * therefore be subdivided into <code>step_sizes[i].size()</code> cells in
309 * coordinate direction <code>i</code>, with width
310 * <code>step_sizes[i][j]</code> for the <code>j</code>th cell.
311 *
312 * This function is therefore the right one to generate graded meshes where
313 * cells are concentrated in certain areas, rather than a uniformly
314 * subdivided mesh as the previous function generates.
315 *
316 * The step sizes have to add up to the dimensions of the hyper rectangle
317 * specified by the points @p p1 and @p p2.
318 *
319 * @note This function is available through the python interface as
320 * `triangulation.generate_subdivided_steps_hyper_rectangle(step_sizes, p1,
321 * p2, colorize = false)`.
322 */
323 template <int dim>
324 void
325 subdivided_hyper_rectangle(Triangulation<dim> &tria,
326 const std::vector<std::vector<double>> &step_sizes,
327 const Point<dim> &p_1,
328 const Point<dim> &p_2,
329 const bool colorize = false);
330
331 /**
332 * Like the previous function, but with the following twist: the @p
333 * material_id argument is a dim-dimensional array that, for each cell,
334 * indicates which material_id should be set. In addition, and this is the
335 * major new functionality, if the material_id of a cell is <tt>(unsigned
336 * char)(-1)</tt>, then that cell is deleted from the triangulation, i.e.
337 * the domain will have a void there.
338 *
339 * @note If you need a lot of holes, you may consider cheese().
340 *
341 * @note This function is available through the python interface as
342 * `triangulation.generate_subdivided_material_hyper_rectangle(spacing, p,
343 * material_id, colorize = false)`.
344 */
345 template <int dim>
346 void
347 subdivided_hyper_rectangle(Triangulation<dim> &tria,
348 const std::vector<std::vector<double>> &spacing,
349 const Point<dim> &p,
350 const Table<dim, types::material_id> &material_id,
351 const bool colorize = false);
352
353 /**
354 * \brief Rectangular domain with rectangular pattern of holes
355 *
356 * The domain itself is rectangular, very much as if it had been generated
357 * by subdivided_hyper_rectangle(). The argument <code>holes</code>
358 * specifies how many square holes the domain should have in each coordinate
359 * direction. The total number of mesh cells in that direction is then twice
360 * this number plus one.
361 *
362 * The number of holes in one direction must be at least one.
363 *
364 * An example with two by three holes is
365 *
366 * @image html cheese_2d.png
367 *
368 * If @p dim < @p spacedim, this will create a @p dim dimensional object in
369 * the first @p dim coordinate directions embedded into the @p spacedim
370 * dimensional space with the remaining entries set to zero.
371 *
372 * @param tria The triangulation to be created. It needs to be empty upon
373 * calling this function.
374 *
375 * @param holes Positive number of holes in each of the dim directions.
376 *
377 * @note This function is available through the python interface as
378 * `triangulation.generate_cheese(holes)`.
379 */
380 template <int dim, int spacedim>
381 void
382 cheese(Triangulation<dim, spacedim> &tria,
383 const std::vector<unsigned int> &holes);
384
385 /**
386 * \brief Rectangular plate with an (offset) cylindrical hole.
387 *
388 * Generate a rectangular plate with an (offset) cylindrical hole. The
389 * geometry consists of 2 regions:
390 * The first is a square region with length @p outer_radius and a hole of radius @p inner_radius .
391 * Cells in this region will have TransfiniteInterpolationManifold with
392 * manifold id @p tfi_manifold_id attached to them. Additionally, the boundary
393 * faces of the hole will be associated with a PolarManifold (in 2d) or
394 * CylindricalManifold (in 3d). The center of this
395 * region can be prescribed via @p center , namely the axis of the hole will
396 * be located at @p center .
397 * The second region describes the remainder of the bulk material. It is
398 * specified via padding
399 * parameters @p pad_bottom, @p padding_top, @p padding_left and @p padding_right.
400 * All cells in this region will have a FlatManifold attached to them.
401 * The final width of the plate will be <code>padding_left + 2*outer_radius +
402 * padding_right</code>, while its length is <code>padding_top +
403 * 2*outer_radius + padding_bottom</code>.
404 *
405 * Here is the non-symmetric grid (after one global refinement, colored
406 * according to manifold id) in 2d and 3d, respectively:
407 *
408 * \htmlonly <style>div.image
409 * img[src="plate_with_a_hole.png"]{width:25%;}</style> \endhtmlonly
410 * @image html plate_with_a_hole.png
411 * \htmlonly <style>div.image
412 * img[src="plate_with_a_hole_3D.png"]{width:25%;}</style> \endhtmlonly
413 * @image html plate_with_a_hole_3D.png
414 *
415 * In 3d, triangulation will be extruded in the z-direction by the total
416 * height of @p L using @p n_slices slices (minimum is 2).
417 *
418 * If the @p colorize flag is <code>true</code>, the boundary_ids of the
419 * boundary faces are assigned such that the lower one in the x-direction is
420 * 0, and the upper one is 1 (see
421 * @ref GlossColorization "the glossary entry on colorization").
422 * The indicators for the surfaces in the y-direction are 2 and 3, and the
423 * ones for the z-direction are 5 and 6. The hole boundary has indicator 4.
424 *
425 * @p tria is the triangulation to be created. It needs to be empty upon
426 * calling this function.
427 *
428 * @note This function is available through the python interface as
429 * `triangulation.generate_plate_with_a_holes(inner_radius = 0.4, outer_radius
430 * = 1, pad_bottom = 2, pad_top = 2., pad_left = 1., pad_right, center =
431 * Point(), polar_manifold = 0, tfi_manifold = 1, L = 1, n_slices = 2,
432 * colorize = false)`.
433 */
434 template <int dim>
435 void
436 plate_with_a_hole(Triangulation<dim> &tria,
437 const double inner_radius = 0.4,
438 const double outer_radius = 1.,
439 const double pad_bottom = 2.,
440 const double pad_top = 2.,
441 const double pad_left = 1.,
442 const double pad_right = 1.,
443 const Point<dim> &center = Point<dim>(),
444 const types::manifold_id polar_manifold_id = 0,
445 const types::manifold_id tfi_manifold_id = 1,
446 const double L = 1.,
447 const unsigned int n_slices = 2,
448 const bool colorize = false);
449
450 /**
451 * Generate a grid consisting of a channel with a cylinder. This is a common
452 * benchmark for Navier-Stokes solvers. The geometry consists of a channel
453 * of size $[0, 2.2] \times [0, 0.41] \times [0, 0.41] $ (where the $z$
454 * dimension is omitted in 2d) with a cylinder, parallel to the $z$ axis
455 * with diameter $0.1$, centered at $(0.2, 0.2, 0)$. The channel has three
456 * distinct regions:
457 * <ol>
458 * <li>If @p n_shells is greater than zero, then there are that many shells
459 * centered around the cylinder,</li>
460 * <li>a blending region between the shells and the rest of the
461 * triangulation, and</li>
462 * <li>a bulk region consisting of Cartesian cells.</li>
463 * </ol>
464 * Since the cylinder is slightly offset from the center of the channel,
465 * this geometry results in vortex shedding at moderate Reynolds
466 * numbers. Here is the grid (without additional global refinement) in 2d:
467 *
468 * @image html channel_with_cylinder_2d.png
469 *
470 * and in 3d:
471 *
472 * @image html channel_with_cylinder_3d.png
473 *
474 * The resulting Triangulation uses three manifolds: a PolarManifold (in 2d)
475 * or CylindricalManifold (in 3d) with manifold id $0$, a
476 * TransfiniteInterpolationManifold with manifold id $1$, and a FlatManifold
477 * everywhere else. For more information on this topic see
478 * @ref GlossManifoldIndicator "the glossary entry on manifold indicators".
479 * The
480 * cell faces on the cylinder and surrounding shells have manifold ids of
481 * $0$, while the cell volumes adjacent to the shells (or, if they do not
482 * exist, the cylinder) have a manifold id of $1$. Put another way: this
483 * grid uses TransfiniteInterpolationManifold to smoothly transition from
484 * the shells (generated with GridGenerator::concentric_hyper_shells) to the
485 * bulk region. All other cell volumes and faces have manifold id
486 * numbers::flat_manifold_id and use FlatManifold. All cells with id
487 * numbers::flat_manifold_id are rectangular prisms aligned with the
488 * coordinate axes.
489 *
490 * The picture below shows part of the 2d grid (using all default arguments
491 * to this function) after two global refinements. The cells with manifold
492 * id $0$ are orange (the polar manifold id), cells with manifold id $1$ are
493 * yellow (the transfinite interpolation manifold id), and the ones with
494 * manifold id numbers::flat_manifold_id are cyan:
495 *
496 * @image html channel_with_cylinder_2d_manifolds.png
497 *
498 * @param tria Triangulation to be created. Must be empty upon calling this
499 * function.
500 *
501 * @param shell_region_width Width of the layer of shells around the cylinder.
502 * This value should be between $0$ and $0.05$; the default value is $0.03$.
503 *
504 * @param n_shells Number of shells to use in the shell layer.
505 *
506 * @param skewness Parameter controlling how close the shells are
507 * to the cylinder: see the mathematical definition given in
508 * GridGenerator::concentric_hyper_shells.
509 *
510 * @param colorize If `true`, then assign different boundary ids to
511 * different parts of the boundary. For more
512 * information on boundary indicators see
513 * @ref GlossBoundaryIndicator "this glossary entry".
514 * The left boundary (at $x = 0$) is assigned an id of $0$, the right
515 * boundary (at $x = 2.2$) is assigned an id of $1$; the boundary of
516 * the obstacle in the middle (i.e., the circle in 2d or the cylinder
517 * walls in 3d) is assigned an id of $2$, and the channel walls are
518 * assigned an id of $3$.
519 *
520 * See the original paper for more information:
521 * @code{.bib}
522 * @inbook{schafer1996,
523 * author = {Sch{\"a}fer, M. and Turek, S. and Durst, F. and Krause, E.
524 * and Rannacher, R.},
525 * title = {Benchmark Computations of Laminar Flow Around a Cylinder},
526 * bookTitle = {Flow Simulation with High-Performance Computers II: DFG
527 * Priority Research Programme Results 1993--1995},
528 * year = {1996},
529 * publisher = {Vieweg+Teubner Verlag},
530 * address = {Wiesbaden},
531 * pages = {547--566},
532 * isbn = {978-3-322-89849-4},
533 * doi = {10.1007/978-3-322-89849-4_39},
534 * url = {https://doi.org/10.1007/978-3-322-89849-4_39}
535 * }
536 * @endcode
537 *
538 * @note This function is available through the python interface as
539 * `triangulation.generate_channel_with_cylinder(shell_region_width = 0.03,
540 * n_shellsa = 2, skewness = 2., colorize = false)`.
541 */
542 template <int dim>
543 void
544 channel_with_cylinder(Triangulation<dim> &tria,
545 const double shell_region_width = 0.03,
546 const unsigned int n_shells = 2,
547 const double skewness = 2.0,
548 const bool colorize = false);
549
550 /**
551 * Generate a grid consisting of a channel with a cylinder where the length,
552 * the height and the depth (in 3D) of the channel can be defined by the user.
553 * This generator is a generalized version of
554 * GridGenerator::channel_with_cylinder. It can be used for benchmarking
555 * Navier-Stokes solvers for various flows around a cylinder cases in 2D or
556 * 3D. The main limitation of this generator is that the diameter of the
557 * cylinder is fixed at one and that the dimensions of the channel along the x
558 * and y dimensions must be an integer multiple of this diameter.
559 * Consequently, the length before the cylinder
560 * ($L_{pre}$), the length after the cylinder ($L_{post}$), the height below
561 * ($H_{below}$) and the height above ($H_{above}$) must be integer values.
562 * The depth of the channel ($W$) can be any real positive number. The
563 * geometry consists of a channel of size $[-L_{pre}, -H_{below}] \times
564 * [L_{post}, H_{above}] \times [0, W] $ (where the $z$ dimension is omitted
565 * in 2d) with a cylinder, parallel to the $z$ axis with diameter $1$,
566 * centered at $(0, 0, 0)$. The channel has three distinct regions: <ol>
567 * <li>If @p n_shells is greater than zero, then there are that many shells
568 * centered around the cylinder,</li>
569 * <li>a blending region between the shells and the rest of the
570 * triangulation, and</li>
571 * <li>a bulk region consisting of Cartesian cells.</li>
572 * </ol>
573 * Here is an example of a grid (without additional global refinement)
574 * where the arguments were {8,16,8,8} and
575 * the default arguments are used for the number of shells and skewness:
576 *
577 * @image html custom_channel_with_cylinder.png
578 *
579 * The resulting Triangulation uses three manifolds: a PolarManifold (in 2d)
580 * or CylindricalManifold (in 3d) with manifold id $0$, a
581 * TransfiniteInterpolationManifold with manifold id $1$, and a FlatManifold
582 * everywhere else. For more information on this topic see
583 * @ref GlossManifoldIndicator "the glossary entry on manifold indicators".
584 * The
585 * cell faces on the cylinder and surrounding shells have manifold ids of
586 * $0$, while the cell volumes adjacent to the shells (or, if they do not
587 * exist, the cylinder) have a manifold id of $1$. Put another way: this
588 * grid uses TransfiniteInterpolationManifold to smoothly transition from
589 * the shells (generated with GridGenerator::concentric_hyper_shells) to the
590 * bulk region. All other cell volumes and faces have manifold id
591 * numbers::flat_manifold_id and use FlatManifold. All cells with id
592 * numbers::flat_manifold_id are rectangular prisms aligned with the
593 * coordinate axes.
594 *
595 *
596 * @param tria Triangulation to be created. Must be empty upon calling this
597 * function.
598 *
599 * @param lengths_and_heights A vector containing the distance of the domain to the center of the cylinder.
600 * The vector must contain 4 unsigned integers which consist in the length (in
601 * number of cylinder diameter) before the cylinder, after the cylinder, below
602 * the cylinder and above the cylinder.
603 *
604 * @param depth The depth of the simulation domain (in 3D, the z axis)
605 *
606 * @param depth_division The number of division along the z axis
607 *
608 * @param shell_region_radius Radius of the layer of shells around the cylinder.
609 * This value should be between larger than 0.5 (the radius of the cylinder)
610 * and smaller than 1 (the half-length of the box around the cylinder).
611 *
612 * @param n_shells Number of shells to use in the shell layer.
613 *
614 * @param skewness Parameter controlling how close the shells are
615 * to the cylinder: see the mathematical definition given in
616 * GridGenerator::concentric_hyper_shells.
617 *
618 * @param use_transfinite_region If `true`, then a tranfinite manifold is used
619 * in the intermediary region between the cylindrical hypershell and the
620 * channel.
621 *
622 * @param colorize If `true`, then assign different boundary ids to
623 * different parts of the boundary. For more
624 * information on boundary indicators see
625 * @ref GlossBoundaryIndicator "this glossary entry".
626 * The left boundary (at $x = -L_{pre}$) is assigned an id of $0$, the right
627 * boundary (at $x = L_{post}$) is assigned an id of $1$; the boundary of
628 * the obstacle in the middle (i.e., the circle in 2d or the cylinder
629 * walls in 3d) is assigned an id of $2$, the bottom wall (at $y=-H$) is
630 * assigned and id of $/$, the top wall (at $y=H$) is assigned an id of $4$.
631 * In 3D, the front wall ($z=0$) is assigned an id of $5$ and the back wall
632 * ($z=W$) is assigned an id of $6$.
633 */
634 template <int dim>
635 void
636 uniform_channel_with_cylinder(
637 Triangulation<dim> &tria,
638 const std::vector<unsigned int> &lengths_and_heights,
639 const double depth = 1,
640 const unsigned int depth_division = 1,
641 const double shell_region_radius = 0.75,
642 const unsigned int n_shells = 2,
643 const double skewness = 2.0,
644 const bool use_transfinite_region = false,
645 const bool colorize = false);
646
647 /**
648 * A general @p dim -dimensional cell (a segment if dim is 1, a quadrilateral
649 * if @p dim is 2, or a hexahedron if @p dim is 3) immersed in a
650 * @p spacedim -dimensional space. It is the responsibility of the user to
651 * provide the vertices in the right order (see the documentation of the
652 * GeometryInfo class) because the vertices are stored in the same order as
653 * they are given. It is also important to make sure that the volume of the
654 * cell is positive.
655 *
656 * If the argument @p colorize is false, then all boundary indicators are
657 * set to zero for 2d and 3d. If it is true, the boundary is colorized as in
658 * hyper_rectangle() (see
659 * @ref GlossColorization "the glossary entry on colorization").
660 * In 1d the
661 * indicators are always colorized, see hyper_rectangle().
662 *
663 * @param tria The triangulation that will be created
664 * @param vertices The 2^dim vertices of the cell
665 * @param colorize If true, set different boundary ids.
666 *
667 * @note This function is available through the python interface as
668 * `triangulation.generate_general_cell(vertices, colorize = false)`.
669 */
670 template <int dim, int spacedim>
671 void
672 general_cell(Triangulation<dim, spacedim> &tria,
673 const std::vector<Point<spacedim>> &vertices,
674 const bool colorize = false);
675
676 /**
677 * A parallelogram. The first corner point is the origin. The next @p dim
678 * vertices are the ones given in the second argument and the last vertex
679 * will be the sum of the two vectors connecting the origin to those
680 * points. Colorizing is done in the same way as in hyper_rectangle().
681 *
682 * @note This function is implemented in 2d only.
683 *
684 * @param tria The triangulation to be created. It needs to be empty upon
685 * calling this function.
686 *
687 * @param corners Second and third vertices of the parallelogram.
688 *
689 * @param colorize Assign different boundary ids if true. (see
690 * @ref GlossColorization "the glossary entry on colorization").
691 *
692 * @note This function is available through the python interface as
693 * `triangulation.generate_parallelogram(vertices, colorize = false)`.
694 */
695 template <int dim>
696 void
697 parallelogram(Triangulation<dim> &tria,
698 const Point<dim> (&corners)[dim],
699 const bool colorize = false);
700
701 /**
702 * A parallelepiped. The first corner point is the origin. The @p dim
703 * adjacent points are vectors describing the edges of the parallelepiped
704 * with respect to the origin. Additional points are sums of these dim
705 * vectors. Colorizing is done according to hyper_rectangle().
706 *
707 * @note This function silently reorders the vertices on the cells to
708 * lexicographic ordering (see GridTools::consistently_order_cells()).
709 * In other words, if reordering of the vertices does occur, the ordering of
710 * vertices in the array of <code>corners</code> will no longer refer to the
711 * same triangulation.
712 *
713 * @pre The triangulation passed as argument needs to be empty when calling
714 * this function.
715 *
716 * @note This function is available through the python interface as
717 * `triangulation.generate_parallelepiped(vertices, colorize = false)`.
718 */
719 template <int dim>
720 void
721 parallelepiped(Triangulation<dim> &tria,
722 const Point<dim> (&corners)[dim],
723 const bool colorize = false);
724
725 /**
726 * A subdivided parallelepiped. The first corner point is the origin. The @p
727 * dim adjacent points are vectors describing the edges of the
728 * parallelepiped with respect to the origin. Additional points are sums of
729 * these dim vectors. The variable @p n_subdivisions designates the number
730 * of subdivisions in each of the @p dim directions. Colorizing is done
731 * according to hyper_rectangle().
732 *
733 * @pre The triangulation passed as argument needs to be empty when calling
734 * this function.
735 *
736 * @note This function is available through the python interface as
737 * `triangulation.generate_fixed_subdivided_parallelepiped(n_subdivisions,
738 * corners, colorize = false)`.
739 */
740 template <int dim>
741 void
742 subdivided_parallelepiped(Triangulation<dim> &tria,
743 const unsigned int n_subdivisions,
744 const Point<dim> (&corners)[dim],
745 const bool colorize = false);
746
747 /**
748 * A subdivided parallelepiped, i.e., the same as above, but where the
749 * number of subdivisions in each of the @p dim directions may vary.
750 * Colorizing is done according to hyper_rectangle().
751 *
752 * @pre The triangulation passed as argument needs to be empty when calling
753 * this function.
754 *
755 * @note This function is available through the python interface as
756 * `triangulation.generate_varying_subdivided_parallelepiped(n_subdivisions,
757 * corners, colorize = false)`.
758 */
759 template <int dim>
760 void
761 subdivided_parallelepiped(Triangulation<dim> &tria,
762 #ifndef _MSC_VER
763 const unsigned int (&n_subdivisions)[dim],
764 #else
765 const unsigned int *n_subdivisions,
766 #endif
767 const Point<dim> (&corners)[dim],
768 const bool colorize = false);
769
770 /**
771 * A subdivided parallelepiped.
772 *
773 * @param tria The triangulation to be created. It needs to be empty upon
774 * calling this function.
775 *
776 * @param origin First corner of the parallelepiped.
777 *
778 * @param edges An array of @p dim tensors describing the length and
779 * direction of the edges from @p origin.
780 *
781 * @param subdivisions Number of subdivisions in each of the dim directions.
782 * Each entry must be positive. An empty vector is equivalent to one
783 * subdivision in each direction.
784 *
785 * @param colorize Assign different boundary ids if set to true (see
786 * @ref GlossColorization "the glossary entry on colorization").
787 *
788 * @note Implemented for all combinations of @p dim and @p spacedim.
789 *
790 * @note You likely need to help the compiler by explicitly specifying the
791 * two template parameters when calling this function.
792 */
793 template <int dim, int spacedim>
794 void
795 subdivided_parallelepiped(Triangulation<dim, spacedim> &tria,
796 const Point<spacedim> &origin,
797 const std::array<Tensor<1, spacedim>, dim> &edges,
798 const std::vector<unsigned int> &subdivisions = {},
799 const bool colorize = false);
800
801 /**
802 * Hypercube with a layer of hypercubes around it. Parameters @p left and
803 * @p right give the lower and upper bound of the inner hypercube in all
804 * coordinate directions. @p thickness marks the size of the layer cells.
805 *
806 * If the flag @p colorize is set, the outer cells get material ids
807 * according to the following scheme: extending over the inner cube in (+/-)
808 * x-direction 1/2, y-direction 4/8, z-direction 16/32. A bitwise OR operation
809 * is used to get these values at the corners and edges (3d), (see also
810 * @ref GlossColorization "the glossary entry on colorization").
811 *
812 * Presently only available in 2d and 3d.
813 *
814 * @pre The triangulation passed as argument needs to be empty when calling
815 * this function.
816 *
817 * @note This function is available through the python interface as
818 * `triangulation.generate_hyper_cube(left = 0, right = 1., thickness = 1.,
819 * colorize = false)`.
820 */
821 template <int dim>
822 void
823 enclosed_hyper_cube(Triangulation<dim> &tria,
824 const double left = 0.,
825 const double right = 1.,
826 const double thickness = 1.,
827 const bool colorize = false);
828
829 /**
830 * Initialize the given triangulation with several
831 * @ref GlossCoarseMesh "coarse mesh cells"
832 * that cover a hyperball, i.e. a circular disk if `dim==2` or a
833 * ball if `dim==3`, around @p center with given @p radius. The function is
834 * used in step-6.
835 *
836 * In order to avoid degenerate cells at the boundaries, the circular disk is
837 * triangulated by five cells, whereas in 3d the ball is subdivided into
838 * seven cells. Specifically, these
839 * cells are one cell in the center plus one "cap" cell on each of the faces
840 * of this center cell. This ensures that under repeated refinement, none
841 * of the cells at the outer boundary will degenerate to have an interior
842 * angle approaching 180 degrees, as opposed to the case where one might
843 * start with just one square (or cube) to approximate the domain.
844 * The diameter of the
845 * center cell is chosen so that the aspect ratio of the boundary cells
846 * after one refinement is optimized.
847 *
848 * This function is declared to exist for triangulations of all space
849 * dimensions, but throws an error if called if `dim==1`. If `spacedim>dim`
850 * (which is only possible if `dim==2, spacedim==3`) then the function
851 * creates a circular disk for which all vertices have a $z$ value equal
852 * to the $z$ coordinate of the center point provided by the second argument.
853 *
854 * By default, the manifold_id is set to 0 on the boundary faces, 1 on the
855 * boundary cells, and numbers::flat_manifold_id on the central cell and on
856 * internal faces.
857 *
858 * A SphericalManifold is attached by default to the boundary faces for
859 * correct placement of boundary vertices upon refinement and to be able to
860 * use higher order mappings. However, it turns out that this strategy may
861 * not be the optimal one to create a good a mesh for a hyperball. The
862 * "Possibilities for extensions" section of step-6 has an extensive
863 * discussion of how one would construct better meshes and what one needs to
864 * do for it. Setting the argument
865 * `attach_spherical_manifold_on_boundary_cells` to true attaches a
866 * SphericalManifold manifold also to the cells adjacent to the boundary, and
867 * not only to the boundary faces.
868 *
869 * @note Since this is likely one of the earliest functions users typically
870 * consider to create meshes with curved boundaries, let us also comment
871 * on one aspect that is often confusing: Namely, that what one sees is not
872 * always what is actually happening. Specifically, if you output the coarse
873 * mesh with a function such as GridOut::write_vtk() using default options,
874 * then one doesn't generally get to see curved faces at the boundary.
875 * That's because most file formats by default only store vertex locations,
876 * with the implicit understanding that cells are composed from these
877 * vertices and bounded by straight edges. At the same time, the fact
878 * that this function attaches a SphericalManifold object to the boundary
879 * faces means that at least *internally*, edges really are curved. If
880 * you want to see them that way, you need to make sure that the function
881 * you use to output the mesh actually plots boundary faces as curved
882 * lines rather than straight lines characterized by only the locations
883 * of the two end points. For example, GridOut::write_gnuplot() can do
884 * that if you set the corresponding flag in the GridOutFlags::Gnuplot
885 * structure. It is, however, an entirely separate consideration whether
886 * you are actually *computing* on curved cells. In typical finite
887 * element computations, one has to compute integrals and these are
888 * computed by transforming back actual cells using a mapping to the
889 * reference cell. What mapping is used determines what shape the
890 * cells have for these internal computations: For example, with the
891 * widely used $Q_1$ mapping (implicitly used in step-6), integration
892 * always happens on cells that are assumed to have straight boundaries
893 * described by only the vertex locations. In other words, if such a
894 * mapping is used, then the cells of the domain really do have
895 * straight edges, regardless of the manifold description attached
896 * to these edges and regardless of the flags given when generating
897 * output. As a consequence of all of this, it is important to
898 * distinguish three things: (i) the manifold description attached to an
899 * object in the mesh; (ii) the mapping used in integration; and (iii) the
900 * style used in outputting graphical information about the mesh. All of
901 * these can be chosen more or less independently of each other, and
902 * what you see visualized is not necessarily exactly what is
903 * happening.
904 *
905 * @pre The triangulation passed as argument needs to be empty when calling
906 * this function.
907 *
908 * @note This function is available through the python interface as
909 * `triangulation.generate_hyper_ball(point, radius = 1.)`.
910 */
911 template <int dim, int spacedim>
912 void
913 hyper_ball(Triangulation<dim, spacedim> &tria,
914 const Point<spacedim> &center = {},
915 const double radius = 1.,
916 const bool attach_spherical_manifold_on_boundary_cells = false);
917
918 /**
919 * This is an alternative to hyper_ball with 12 cells in 2d and 32 cells in
920 * 3d, which provides a better balance between the size of the cells around
921 * the outer curved boundaries and the cell in the interior. The mesh is
922 * based on the cells used by GridGenerator::quarter_hyper_ball() with
923 * appropriate copies and rotations to fill the whole ball.
924 *
925 * The following pictures show the resulting mesh in 2d (left) and 3d:
926 * <table align="center" class="doxtable">
927 * <tr>
928 * <td>
929 * \htmlonly <style>div.image
930 * img[src="hyper_ball_balanced_2d.png"]{width:40%}</style>
931 * \endhtmlonly
932 * @image html hyper_ball_balanced_2d.png
933 * </td>
934 * <td>
935 * \htmlonly <style>div.image
936 * img[src="hyper_ball_balanced_3d.png"]{width:40%}</style>
937 * \endhtmlonly
938 * @image html hyper_ball_balanced_3d.png
939 * </td>
940 * </tr>
941 * </table>
942 *
943 * By default, the manifold_id is set to 0 on the boundary faces, 1 on the
944 * boundary cells, and numbers::flat_manifold_id on the central cell and on
945 * internal faces.
946 *
947 * @pre The triangulation passed as argument needs to be empty when calling
948 * this function.
949 *
950 * @note This function is available through the python interface as
951 * `triangulation.generate_hyper_ball_balanced(point = Point(), radius = 1.)`.
952 */
953 template <int dim>
954 void
955 hyper_ball_balanced(Triangulation<dim> &tria,
956 const Point<dim> &center = Point<dim>(),
957 const double radius = 1.);
958
959 /**
960 * Generate a 2d mesh consisting of five squares arranged in a plus-shape.
961 * Depending on the number <code>n_rotate_middle_square</code> passed the
962 * middle square is rotated by a degree of
963 * <code>n_rotate_middle_square</code>$\pi/2$. This way one can generate a
964 * mesh in which the middle square contains edges that have the opposite
965 * tangential and/or opposite normal orientation compared to the neighboring
966 * edges of the other squares.
967 *
968 * This mesh is not overly useful from a practical point of view. For
969 * debugging purposes it can be used to check for orientation issues for
970 * vector- or tensor-valued finite elements.
971 *
972 * @param[out] tria The input triangulation.
973 * @param[in] n_rotate_middle_square number of rotations in [0,4) of right
974 * square by
975 * $\pi/2$.
976 */
977 void
978 non_standard_orientation_mesh(Triangulation<2> &tria,
979 const unsigned int n_rotate_middle_square);
980
981 /**
982 * Generate a 3d mesh consisting of the unit cube joined with a copy shifted
983 * by $s = (1,0,0)$. Depending on the flags passed either the right or the
984 * left cube (when looking at the positively oriented (x,z)-plane) contains a
985 * face that is either not in standard orientation and/or is rotated by either
986 * $\pi/2$, $\pi$ or $3/2\pi$.
987 *
988 * This mesh is not overly useful from a practical point of view. For
989 * debugging purposes it can be used to check for orientation issues for
990 * vector- or tensor-valued finite elements.
991 *
992 * @param[out] tria The input triangulation.
993 * @param[in] face_orientation <code>true</code> if the face is the not in
994 * standard orientation.
995 * @param[in] face_flip <code>true</code> if the face is rotated by +180
996 * degrees
997 * @param[in] face_rotation <code>true</code> if the face is rotated
998 * (additionally) by +90 degrees
999 * @param[in] manipulate_left_cube <code>true</code> if the left cube is
1000 * to be re-ordered. If `false`, it is the right cube.
1001 */
1002 void
1003 non_standard_orientation_mesh(Triangulation<3> &tria,
1004 const bool face_orientation,
1005 const bool face_flip,
1006 const bool face_rotation,
1007 const bool manipulate_left_cube);
1008
1009
1010 /**
1011 * Creates a hyper sphere, i.e., a surface of a ball in @p spacedim
1012 * dimensions. This function only exists for dim+1=spacedim in 2 and 3 space
1013 * dimensions. (To create a mesh of a ball, use GridGenerator::hyper_ball().)
1014 *
1015 * By default, all manifold ids of the triangulation are set to zero, and a
1016 * SphericalManifold is attached to the grid.
1017 *
1018 * The following pictures are generated with:
1019 * @code
1020 * Triangulation<2,3> triangulation;
1021 * GridGenerator::hyper_sphere(triangulation);
1022 * triangulation.refine_global(3);
1023 * @endcode
1024 *
1025 * See the
1026 * @ref manifold "documentation topic on manifolds"
1027 * for more details.
1028 *
1029 * @image html sphere.png
1030 * @image html sphere_section.png
1031 *
1032 * @pre The triangulation passed as argument needs to be empty when calling
1033 * this function.
1034 *
1035 * @note This function is available through the python interface as
1036 * `triangulation.generate_hyper_sphere(center, radius = 1.)`.
1037 */
1038 template <int spacedim>
1039 void
1040 hyper_sphere(Triangulation<spacedim - 1, spacedim> &tria,
1041 const Point<spacedim> &center = Point<spacedim>(),
1042 const double radius = 1.);
1043
1044 /**
1045 * This function produces a hyper-ball intersected with the positive orthant
1046 * relative to @p center, which contains three elements in 2d and four in
1047 * 3d. The interior points of the mesh are chosen to balance the minimal
1048 * singular value of the Jacobian of the mapping from reference to real
1049 * coordinates among the cells around the interior point, which corresponds
1050 * to a high mesh quality.
1051 *
1052 * The boundary indicators for the final triangulation are 0 for the curved
1053 * boundary and 1 for the cut plane. The manifold id for the curved boundary
1054 * is set to zero, and a SphericalManifold is attached to it.
1055 *
1056 * The resulting grid in 2d and 3d looks as follows:
1057 * <table align="center" class="doxtable">
1058 * <tr>
1059 * <td>
1060 * \htmlonly <style>div.image
1061 * img[src="quarter_hyper_ball_2d.png"]{width:50%}</style>
1062 * \endhtmlonly
1063 * @image html quarter_hyper_ball_2d.png
1064 * </td>
1065 * <td>
1066 * \htmlonly <style>div.image
1067 * img[src="quarter_hyper_ball_3d.png"]{width:46%}</style>
1068 * \endhtmlonly
1069 * @image html quarter_hyper_ball_3d.png
1070 * </td>
1071 * </tr>
1072 * </table>
1073 *
1074 * @pre The triangulation passed as argument needs to be empty when calling
1075 * this function.
1076 *
1077 * @note This function is available through the python interface as
1078 * `triangulation.generate_quarter_hyper_ball(center, radius = 1.)`.
1079 */
1080 template <int dim>
1081 void
1082 quarter_hyper_ball(Triangulation<dim> &tria,
1083 const Point<dim> &center = Point<dim>(),
1084 const double radius = 1.);
1085
1086 /**
1087 * This function produces a half hyper-ball around @p center, which contains
1088 * four elements in 2d and 6 in 3d. The cut plane is perpendicular to the
1089 * <i>x</i>-axis.
1090 *
1091 * The boundary indicators for the final triangulation are 0 for the curved
1092 * boundary and 1 for the cut plane. The manifold id for the curved boundary
1093 * is set to zero, and a SphericalManifold is attached to it.
1094 *
1095 * @pre The triangulation passed as argument needs to be empty when calling
1096 * this function.
1097 *
1098 * @note This function is available through the python interface as
1099 * `triangulation.generate_half_hyper_ball(center, radius = 1.)`.
1100 */
1101 template <int dim>
1102 void
1103 half_hyper_ball(Triangulation<dim> &tria,
1104 const Point<dim> &center = Point<dim>(),
1105 const double radius = 1.);
1106
1107 /**
1108 * Create a @p dim dimensional cylinder where the $x$-axis serves as
1109 * the axis of the cylinder. For the purposes of this function, a
1110 * cylinder is defined as a (@p dim - 1) dimensional disk of given
1111 * @p radius, extruded along the axis of the cylinder (which is the
1112 * first coordinate direction). Consequently, in three dimensions,
1113 * the cylinder extends from `x=-half_length` to `x=+half_length`
1114 * and its projection into the @p yz-plane is a circle of radius @p
1115 * radius. In two dimensions, the cylinder is a rectangle from
1116 * `x=-half_length` to `x=+half_length` and from `y=-radius` to
1117 * `y=radius`.
1118 *
1119 * The boundaries are colored according to the following scheme: 0 for the
1120 * hull of the cylinder, 1 for the left hand face and 2 for the right hand
1121 * face (see
1122 * @ref GlossColorization "the glossary entry on colorization").
1123 *
1124 * The manifold id for the hull of the cylinder is set to zero, and a
1125 * CylindricalManifold is attached to it.
1126 *
1127 * @pre The triangulation passed as argument needs to be empty when calling
1128 * this function.
1129 *
1130 * @note This function is available through the python interface as
1131 * `triangulation.generate_cylinder(radius = 1., half_length = 1.)`.
1132 */
1133 template <int dim>
1134 void
1135 cylinder(Triangulation<dim> &tria,
1136 const double radius = 1.,
1137 const double half_length = 1.);
1138
1139
1140 /**
1141 * Create a @p dim dimensional cylinder where the $x$-axis serves as
1142 * the axis of the cylinder. For the purposes of this function, a
1143 * cylinder is defined as a (@p dim - 1) dimensional disk of given
1144 * @p radius, extruded along the axis of the cylinder (which is the
1145 * first coordinate direction). Consequently, in three dimensions,
1146 * the cylinder extends from `x=-half_length` to `x=+half_length`
1147 * and its projection into the @p yz-plane is a circle of radius @p
1148 * radius. In two dimensions, the cylinder is a rectangle from
1149 * `x=-half_length` to `x=+half_length` and from `y=-radius` to
1150 * `y=radius`. This function is only implemented for dim==3.
1151 *
1152 * The boundaries are colored according to the following scheme: 0 for the
1153 * hull of the cylinder, 1 for the left hand face and 2 for the right hand
1154 * face (see
1155 * @ref GlossColorization "the glossary entry on colorization").
1156 *
1157 * The manifold id for the hull of the cylinder is set to zero, and a
1158 * CylindricalManifold is attached to it.
1159 *
1160 * @image html subdivided_cylinder_3D.png
1161 *
1162 * @param tria The triangulation to be created. It needs to be empty upon
1163 * calling this function.
1164 *
1165 * @param x_subdivisions A positive integer denoting the number
1166 * of cells to generate in the x direction. The default cylinder has
1167 * x_repetitions=2.
1168 *
1169 * @param radius The radius of the circle in the yz-plane used to extrude the cylinder.
1170 *
1171 * @param half_length The half-length of the cylinder in the x direction.
1172 *
1173 * @note This function is available through the python interface as
1174 * `triangulation.generate_subdivided_cylinder(x_subdivisions, radius = 1.,
1175 * half_length = 1.)`.
1176 */
1177 template <int dim>
1178 void
1179 subdivided_cylinder(Triangulation<dim> &tria,
1180 const unsigned int x_subdivisions,
1181 const double radius = 1.,
1182 const double half_length = 1.);
1183
1184
1185 /**
1186 * Create a cut cone around the x-axis. The cone extends from
1187 * <tt>x=-half_length</tt> to <tt>x=half_length</tt> and its projection into
1188 * the @p yz-plane is a circle of radius @p radius_0 at
1189 * <tt>x=-half_length</tt> and a circle of radius @p radius_1 at
1190 * <tt>x=+half_length</tt>. In between the radius is linearly decreasing.
1191 *
1192 * In two dimensions, the cone is a trapezoid from <tt>x=-half_length</tt>
1193 * to <tt>x=+half_length</tt> and from <tt>y=-radius_0</tt> to
1194 * <tt>y=radius_0</tt> at <tt>x=-half_length</tt> and from
1195 * <tt>y=-radius_1</tt> to <tt>y=radius_1</tt> at <tt>x=+half_length</tt>.
1196 * In between the range of <tt>y</tt> is linearly decreasing.
1197 *
1198 * The boundaries are colored according to the following scheme: 0 for the
1199 * hull of the cone, 1 for the left hand face, and 2 for the right hand face
1200 * (see
1201 * @ref GlossColorization "the glossary entry on colorization").
1202 * Both the boundary indicators and the manifold indicators are set.
1203 *
1204 * In three dimensions, the manifold id of the hull is set to zero, and a
1205 * CylindricalManifold is attached to it.
1206 *
1207 * Here are the grids in 2d and 3d after two mesh refinements:
1208 *
1209 * @image html truncated_cone_2d.png
1210 * @image html truncated_cone_3d.png
1211 *
1212 * @pre The triangulation passed as argument needs to be empty when calling
1213 * this function.
1214 *
1215 * @note This function is available through the python interface as
1216 * `triangulation.generate_truncated_cone(radius_0 = 1., radius_2 = 0.5,
1217 * half_length = 1.)`.
1218 */
1219 template <int dim>
1220 void
1221 truncated_cone(Triangulation<dim> &tria,
1222 const double radius_0 = 1.0,
1223 const double radius_1 = 0.5,
1224 const double half_length = 1.0);
1225
1226 /**
1227 * Initialize the given triangulation with a pipe junction, which is the
1228 * intersection of three truncated cones.
1229 *
1230 * The geometry has four characteristic cross sections, located at the three
1231 * openings and the bifurcation. They need to be specified via the function's
1232 * arguments: each cross section is described by a characteristic point and a
1233 * radius. The cross sections at the openings are circles and are described by
1234 * their center point and radius. The bifurcation point describes where the
1235 * symmetry axes of all cones meet.
1236 *
1237 * Each truncated cone is transformed so that the three merge seamlessly into
1238 * each other. The bifurcation radius describes the radius that each original,
1239 * untransformed, truncated cone would have at the bifurcation. This radius is
1240 * necessary for the construction of the geometry and can, in general, no
1241 * longer be found in the final result.
1242 *
1243 * Each cone will be assigned a distinct <em>material ID</em> that matches the
1244 * index of their opening in the argument @p openings. For example, the cone
1245 * which connects to opening with index 0 in @p openings will have material ID 0.
1246 *
1247 * Similarly, <em>boundary IDs</em> are assigned to the cross-sections of each
1248 * opening to match their index. All other boundary faces will be assigned
1249 * boundary ID 3.
1250 *
1251 * @ref GlossManifoldIndicator "Manifold IDs"
1252 * will be set on the mantles of each truncated cone in
1253 * the same way. Each cone will have a special manifold object assigned, which
1254 * is based on the CylindricalManifold class. Further, all cells adjacent to
1255 * the mantle are given the manifold ID 3. If desired, you can assign an
1256 * (expensive) TransfiniteInterpolationManifold object to that particular
1257 * layer of cells with the following code snippet.
1258 * @code
1259 * TransfiniteInterpolationManifold<3> transfinite;
1260 * transfinite.initialize(triangulation);
1261 * triangulation.set_manifold(3, transfinite);
1262 * @endcode
1263 *
1264 * @pre The triangulation passed as argument needs to be empty when calling
1265 * this function.
1266 *
1267 * @note Only implemented for `dim = 3` and `spacedim = 3`.
1268 *
1269 * @param tria An empty triangulation which will hold the pipe junction geometry.
1270 * @param openings Center point and radius of each of the three openings.
1271 * The container has to be of size three.
1272 * @param bifurcation Center point of the bifurcation and hypothetical radius of
1273 * each truncated cone at the bifurcation.
1274 * @param aspect_ratio Aspect ratio of cells, specified as radial over z-extension.
1275 * Default ratio is $\Delta r/\Delta z = 1/2$.
1276 *
1277 * Common configurations of tee fittings (that is, "T" fittings, mimicking the
1278 * geometry of the letter "T") can be generated with the
1279 * following sets of parameters:
1280 * <div class="threecolumn" style="width: 80%; text-align: center;">
1281 * <div>
1282 * \htmlonly <style>div.image
1283 * img[src="tee_corner.png"]{width:100%}</style>
1284 * \endhtmlonly
1285 * @image html tee_corner.png
1286 * <table class="doxtable" style="display: inline-table;">
1287 * <tr><th colspan="3">Corner piece
1288 * <tr><td>
1289 * <td>Point
1290 * <td>Radius
1291 * <tr><td rowspan="3">Openings
1292 * <td>$(2,0,0)$
1293 * <td>$1$
1294 * <tr><td>$(0,2,0)$
1295 * <td>$1$
1296 * <tr><td>$(0,0,2)$
1297 * <td>$1$
1298 * <tr><td>Bifurcation
1299 * <td>$(0,0,0)$
1300 * <td>$1$
1301 * </table>
1302 * </div>
1303 * <div>
1304 * \htmlonly <style>div.image
1305 * img[src="tee_tpipe.png"]{width:100%}</style>
1306 * \endhtmlonly
1307 * @image html tee_tpipe.png
1308 * <table class="doxtable" style="display: inline-table;">
1309 * <tr><th colspan="3">T-pipe
1310 * <tr><td>
1311 * <td>Point
1312 * <td>Radius
1313 * <tr><td rowspan="3">Openings
1314 * <td>$(-2,0,0)$
1315 * <td>$1$
1316 * <tr><td>$(0,2,0)$
1317 * <td>$1$
1318 * <tr><td>$(2,0,0)$
1319 * <td>$1$
1320 * <tr><td>Bifurcation
1321 * <td>$(0,0,0)$
1322 * <td>$1$
1323 * </table>
1324 * </div>
1325 * <div>
1326 * \htmlonly <style>div.image
1327 * img[src="tee_ypipe.png"]{width:100%}</style>
1328 * \endhtmlonly
1329 * @image html tee_ypipe.png
1330 * <table class="doxtable" style="display: inline-table;">
1331 * <tr><th colspan="3">Y-pipe
1332 * <tr><td>
1333 * <td>Point
1334 * <td>Radius
1335 * <tr><td rowspan="3">Openings
1336 * <td>$(-2,0,0)$
1337 * <td>$1$
1338 * <tr><td>$(1,\sqrt{3},0)$
1339 * <td>$1$
1340 * <tr><td>$(1,-\sqrt{3},0)$
1341 * <td>$1$
1342 * <tr><td>Bifurcation
1343 * <td>$(0,0,0)$
1344 * <td>$1$
1345 * </table>
1346 * </div>
1347 * </div>
1348 */
1349 template <int dim, int spacedim>
1350 void
1351 pipe_junction(Triangulation<dim, spacedim> &tria,
1352 const std::vector<std::pair<Point<spacedim>, double>> &openings,
1353 const std::pair<Point<spacedim>, double> &bifurcation,
1354 const double aspect_ratio = 0.5);
1355
1356 /**
1357 * \brief A center cell with stacks of cell protruding from each surface.
1358 *
1359 * Each of the square mesh cells is Cartesian and has size one in each
1360 * coordinate direction. The center of cell number zero is the origin.
1361 *
1362 * @param tria A Triangulation object which has to be empty.
1363 *
1364 * @param sizes A vector of integers of dimension
1365 * GeometryInfo<dim>::faces_per_cell with the following meaning: the legs of
1366 * the cross are stacked on the faces of the center cell, in the usual order
1367 * of deal.II cells, namely first $-x$, then $x$, then $-y$ and so on. The
1368 * corresponding entries in <code>sizes</code> name the number of cells
1369 * stacked on this face. All numbers may be zero, thus L- and T-shaped
1370 * domains are specializations of this domain.
1371 *
1372 * @param colorize_cells If colorization is enabled, then the material id of
1373 * a cells corresponds to the leg it is in. The id of the center cell is
1374 * zero, and then the legs are numbered starting at one (see
1375 * @ref GlossColorization "the glossary entry on colorization").
1376 *
1377 * Examples in two and three dimensions are:
1378 *
1379 * @image html hyper_cross_2d.png
1380 * @image html hyper_cross_3d.png
1381 */
1382 template <int dim, int spacedim>
1383 void
1384 hyper_cross(Triangulation<dim, spacedim> &tria,
1385 const std::vector<unsigned int> &sizes,
1386 const bool colorize_cells = false);
1387
1388 /**
1389 * Initialize the given triangulation with a hyper-L (in 2d or 3d)
1390 * consisting of exactly <tt>2^dim-1</tt> cells. It produces the
1391 * hypercube with the interval [<i>left,right</i>] without the
1392 * hypercube made out of the interval [<i>(left+right)/2,right</i>]
1393 * for each coordinate. Because the domain is about the simplest one
1394 * with a reentrant (i.e., non-convex) corner, solutions of many
1395 * partial differential equations have singularities at this
1396 * corner. That is, at the corner, the gradient or a higher
1397 * derivative (depending on the boundary conditions chosen) does not
1398 * remain bounded. As a consequence, this domain is often used to
1399 * test convergence of schemes when the solution lacks regularity.
1400 *
1401 * If the @p colorize flag is <code>true</code>, the @p boundary_ids of the
1402 * surfaces are assigned such that the left boundary is 0 and the others are
1403 * assigned counterclockwise in ascending order (see
1404 * @ref GlossColorization "the glossary entry on colorization").
1405 * The @p colorize option only works in two dimensions.
1406 *
1407 * This function will create the classical L-shape in 2d
1408 * and it will look like the following in 3d:
1409 *
1410 * @image html hyper_l.png
1411 *
1412 * @note The 3d domain is also often referred to as the "Fichera corner",
1413 * named after Gaetano Fichera (1922-1996) who first computed an
1414 * approximation of the corner singularity exponent of the lowest
1415 * eigenfunction of the domain.
1416 *
1417 * This function exists for triangulations of all space
1418 * dimensions, but throws an error if called in 1d.
1419 *
1420 * @pre The triangulation passed as argument needs to be empty when calling
1421 * this function.
1422 */
1423 template <int dim>
1424 void
1425 hyper_L(Triangulation<dim> &tria,
1426 const double left = -1.,
1427 const double right = 1.,
1428 const bool colorize = false);
1429
1430 /**
1431 * Initialize the given triangulation in 2d or 3d with a generalized
1432 * subdivided hyper-L.
1433 *
1434 * This function produces a subdivided hyper rectangle with dimensions given
1435 * by @p bottom_left and @p top_right, with the given number of
1436 * subdivisions in each direction given in the vector @p repetitions,
1437 * and with a number of cells removed, given in the vector @p n_cells_to_remove.
1438 * Note that @p n_cells_to_remove contains integers, meaning that its entries
1439 * can be both positive and negative. A positive number denotes
1440 * cutting away cells in the 'positive' orientation, for example
1441 * left to right in the x-direction, bottom to top in
1442 * the y-direction, and front to back in the z-direction. A negative number
1443 * denotes cutting away cells in the reverse direction, so right to left,
1444 * top to bottom, and back to front.
1445 *
1446 * A demonstration of this grid can be found in step-75.
1447 *
1448 * This function may be used to generate a mesh for a backward
1449 * facing step, a useful domain for benchmark problems in fluid dynamics.
1450 * The first image is a backward facing step in 3d, generated by
1451 * removing all cells in the z-direction, and 2 cells in the
1452 * positive x- and y-directions:
1453 * @image html subdivided_hyper_L_3d.png
1454 * And in 2d, we can cut away 1 cell in the negative x-direction, and 2 cells
1455 * in the negative y-direction:
1456 * @image html subdivided_hyper_L_2d.png
1457 *
1458 * @note This function is declared to exist for triangulations of all space
1459 * dimensions, but throws an error if called in 1d.
1460 */
1461 template <int dim, int spacedim>
1462 void
1463 subdivided_hyper_L(Triangulation<dim, spacedim> &tria,
1464 const std::vector<unsigned int> &repetitions,
1465 const Point<dim> &bottom_left,
1466 const Point<dim> &top_right,
1467 const std::vector<int> &n_cells_to_remove);
1468
1469 /**
1470 * Initialize the given Triangulation with a hypercube with a slit. In each
1471 * coordinate direction, the hypercube extends from @p left to @p right.
1472 *
1473 * In 2d, the split goes in vertical direction from <tt>x=(left+right)/2,
1474 * y=left</tt> to the center of the square at <tt>x=y=(left+right)/2</tt>.
1475 *
1476 * In 3d, the 2d domain is just extended in the <i>z</i>-direction, such
1477 * that a plane cuts the lower half of a rectangle in two. This function is
1478 * declared to exist for triangulations of all space dimensions, but throws
1479 * an error if called in 1d.
1480 *
1481 * If @p colorize is set to @p true, the faces forming the slit are marked
1482 * with boundary id 1 and 2, respectively (see
1483 * @ref GlossColorization "the glossary entry on colorization").
1484 *
1485 * @pre The triangulation passed as argument needs to be empty when calling
1486 * this function.
1487 */
1488 template <int dim>
1489 void
1490 hyper_cube_slit(Triangulation<dim> &tria,
1491 const double left = 0.,
1492 const double right = 1.,
1493 const bool colorize = false);
1494
1495 /**
1496 * Produce a hyper-shell, the region between two spheres around
1497 * <tt>center</tt>, with given <tt>inner_radius</tt> and
1498 * <tt>outer_radius</tt>. The number <tt>n_cells</tt> indicates the number
1499 * of cells of the resulting triangulation, i.e., how many cells form the
1500 * ring (in 2d) or the shell (in 3d).
1501 *
1502 * If the flag @p colorize is <code>true</code>, then the outer boundary
1503 * will have the indicator 1 while the inner boundary has id zero. In 3d,
1504 * this applies to both the faces and the edges of these boundaries. If the
1505 * flag is @p false, both have indicator zero (see
1506 * @ref GlossColorization "the glossary entry on colorization").
1507 *
1508 * All manifold ids are set to zero, and a SphericalManifold is attached to
1509 * every cell and face of the triangulation.
1510 *
1511 * In 2d, the number <tt>n_cells</tt> of elements for this initial
1512 * triangulation can be chosen arbitrarily. If the number of initial cells
1513 * is zero (as is the default), then it is computed adaptively such that the
1514 * resulting elements have the least aspect ratio.
1515 *
1516 * In 3d, only certain numbers are allowed:
1517 * <ul>
1518 * <li> 6 (or the default 0) for a surface based on a hexahedron (i.e. 6
1519 * panels on the inner sphere extruded in radial direction to form 6
1520 * cells),
1521 * <li> 12 for the rhombic dodecahedron,
1522 * <li> 24 for the hexahedron-based surface refined once in the azimuthal
1523 * directions but not in the radial direction,
1524 * <li> 48 for the rhombic dodecahedron refined once in the azimuthal
1525 * directions but not in the radial direction,
1526 * <li> 96 for the rhombic dodecahedron refined once. This choice dates from
1527 * an older version of deal.II before the Manifold classes were
1528 * implemented: today this choce is equivalent to the rhombic
1529 * dodecahedron after performing one global refinement.
1530 * <li> Numbers of the kind $192\times 2^m$ with $m\geq 0$ integer. This
1531 * choice is similar to the 24 and 48 cell cases, but provides
1532 * additional refinements in azimuthal direction combined with a single
1533 * layer in radial direction. The base mesh is either the 6 or 12 cell
1534 * version, depending on whether $m$ in the power is odd or even,
1535 * respectively.
1536 * </ul>
1537 * The versions with 24, 48, and $2^m 192$ cells are useful if the shell is
1538 * thin and the radial lengths should be made more similar to the
1539 * circumferential lengths.
1540 *
1541 * The 3d grids with 12 and 96 cells are plotted below:
1542 *
1543 * @image html hypershell3d-12.png
1544 * @image html hypershell3d-96.png
1545 *
1546 * @note This function is declared to exist for triangulations of all space
1547 * dimensions, but throws an error if called in 1d.
1548 *
1549 * @pre The triangulation passed as argument needs to be empty when calling
1550 * this function.
1551 *
1552 * @note This function is available through the python interface as
1553 * `triangulation.generate_hyper_shell(center, inner_radius, outer_radius,
1554 * n_cells = 0, colorize = false)`.
1555 */
1556 template <int dim, int spacedim>
1557 void
1558 hyper_shell(Triangulation<dim, spacedim> &tria,
1559 const Point<spacedim> &center,
1560 const double inner_radius,
1561 const double outer_radius,
1562 const unsigned int n_cells = 0,
1563 bool colorize = false);
1564
1565 /**
1566 * Produce an eccentric hyper-shell, the region between two spheres centered
1567 * on two distinct center points. One has to specify the <tt>inner_center</tt>
1568 * and <tt>outer_center</tt>, with given <tt>inner_radius</tt> and
1569 * <tt>outer_radius</tt>. The number <tt>n_cells</tt> indicates the number of
1570 * cells of the resulting triangulation, i.e., how many cells form the ring
1571 * (in 2d) or the shell (in 3d).
1572 *
1573 * By default, the outer boundary has the indicator 1 while the inner boundary
1574 * has id 0. In 3d, this applies to both the faces and the edges of these
1575 * boundaries.
1576 *
1577 * A SphericalManifold is attached to the outer boundary with an id of 1 while
1578 * another SphericalManifold is attached to the inner boundary with an id of
1579 * 0. A TransfiniteInterpolationManifold is attached to all other cells and
1580 * faces of the triangulation with an id of 2.
1581 *
1582 * Here, the number <tt>n_cells</tt> of elements has the same meaning as in
1583 * GridGenerator::hyper_shell.
1584 *
1585 * The grids with a 30% offset of the inner shell in the x direction, 12
1586 * initial cells and 3 levels of global refinement are plotted below:
1587 *
1588 * @image html eccentric_hyper_shell_2D.png
1589 * @image html eccentric_hyper_shell_3D.png
1590 *
1591 * @note Because it uses the definition of the hyper shell, this function is
1592 * declared to exist for triangulations of all space dimensions, but throws an
1593 * error if called in 1d.
1594 *
1595 * @pre The triangulation passed as argument needs to be empty when calling
1596 * this function.
1597 */
1598 template <int dim>
1599 void
1600 eccentric_hyper_shell(Triangulation<dim> &triangulation,
1601 const Point<dim> &inner_center,
1602 const Point<dim> &outer_center,
1603 const double inner_radius,
1604 const double outer_radius,
1605 const unsigned int n_cells);
1606
1607 /**
1608 * Produce a half hyper-shell, i.e. the space between two circles in two
1609 * space dimensions and the region between two spheres in 3d, with given
1610 * inner and outer radius and a given number of elements for this initial
1611 * triangulation. However, opposed to the previous function, it does not
1612 * produce a whole shell, but only one half of it, namely that part for
1613 * which the first component is restricted to non-negative values. The
1614 * purpose of this function is to enable computations for solutions which have
1615 * rotational symmetry, in which case the half shell in 2d represents a
1616 * shell in 3d.
1617 *
1618 * If the number of initial cells @p n_cells is zero in 2d (as is the
1619 * default), then it is computed adaptively such that the resulting elements
1620 * have the least aspect ratio. The argument is ignored in 3d, where the
1621 * coarse mesh always has 5 cells.
1622 *
1623 * If colorize is set to <code>true</code>, the inner, outer, and the part
1624 * of the boundary where $x=0$, get indicator 0, 1, and 2,
1625 * respectively. Additionally, in 2d, the boundary indicator 3 is given to
1626 * the vertical edge below the x-axis. Otherwise, if colorize is set to
1627 * <code>false</code> all indicators are set to 0 (see
1628 * @ref GlossColorization "the glossary entry on colorization").
1629 *
1630 * All manifold ids are set to zero, and a SphericalManifold is attached
1631 * to the triangulation.
1632 *
1633 * @pre The triangulation passed as argument needs to be empty when calling
1634 * this function.
1635 */
1636 template <int dim>
1637 void
1638 half_hyper_shell(Triangulation<dim> &tria,
1639 const Point<dim> &center,
1640 const double inner_radius,
1641 const double outer_radius,
1642 const unsigned int n_cells = 0,
1643 const bool colorize = false);
1644
1645
1646 /**
1647 * Produce a domain that is the intersection between a hyper-shell with
1648 * given inner and outer radius, i.e. the space between two circles in two
1649 * space dimensions and the region between two spheres in 3d, and the
1650 * positive quadrant (in 2d) or octant (in 3d). In 2d, this is indeed a
1651 * quarter of the full annulus, while the function is a misnomer in 3d
1652 * because there the domain is not a quarter but one eighth of the full
1653 * shell.
1654 *
1655 * If the number of initial cells is zero (as is the default), then it is
1656 * computed adaptively such that the resulting elements have the least
1657 * aspect ratio in 2d.
1658 *
1659 * If @p colorize is set to <code>true</code>, the inner, outer, left, and
1660 * right boundary get indicator 0, 1, 2, and 3 in 2d,
1661 * respectively. Otherwise all indicators are set to 0. In 3d indicator 2 is
1662 * at the face $x=0$, 3 at $y=0$, 4 at $z=0$ (see
1663 * @ref GlossColorization "the glossary entry on colorization").
1664 *
1665 * All manifold ids are set to zero, and a SphericalManifold is attached
1666 * to the triangulation.
1667 *
1668 * @pre The triangulation passed as argument needs to be empty when calling
1669 * this function.
1670 */
1671 template <int dim>
1672 void
1673 quarter_hyper_shell(Triangulation<dim> &tria,
1674 const Point<dim> &center,
1675 const double inner_radius,
1676 const double outer_radius,
1677 const unsigned int n_cells = 0,
1678 const bool colorize = false);
1679
1680 /**
1681 * Produce a domain that is the space between two cylinders in 3d, with
1682 * given length, inner and outer radius and a given number of elements. The
1683 * cylinder shell is built around the $z$-axis with the two faces located
1684 * at $z = 0$ and $z = $ @p length.
1685 *
1686 * If @p n_radial_cells is zero (as is the
1687 * default), then it is computed adaptively such that the resulting elements
1688 * have the least aspect ratio. The same holds for @p n_axial_cells.
1689 *
1690 * If @p colorize is set to true, a boundary id of 0 is set for the inner
1691 * cylinder, a boundary id of 1 is set for the outer cylinder, a boundary
1692 * id of 2 is set for the bottom (z-) boundary and a boundary id of 3
1693 * is set for the top (z+) boundary.
1694 *
1695 * @note Although this function is declared as a template, it does not make
1696 * sense in 1d and 2d. Also keep in mind that this object is rotated
1697 * and positioned differently than the one created by cylinder().
1698 *
1699 * All manifold ids are set to zero, and a CylindricalManifold is attached
1700 * to the triangulation.
1701 *
1702 * @pre The triangulation passed as argument needs to be empty when calling
1703 * this function.
1704 *
1705 * @image html cylinder_shell.png
1706 *
1707 * In this picture, a cylinder shell of length 2, inner radius 0.5, outer
1708 * radius 1 is shown. The default argument for n_radial_cells and
1709 * n_axial_cells are used and a single global refinement is carried out.
1710 */
1711 template <int dim>
1712 void
1713 cylinder_shell(Triangulation<dim> &tria,
1714 const double length,
1715 const double inner_radius,
1716 const double outer_radius,
1717 const unsigned int n_radial_cells = 0,
1718 const unsigned int n_axial_cells = 0,
1719 const bool colorize = false);
1720
1721 /**
1722 * Produce the volume or surface mesh of a torus. The axis of the torus is
1723 * the $y$-axis while the plane of the torus is the $x$-$z$ plane.
1724 *
1725 * If @p dim is 3, the mesh will be the volume of the torus, using a mesh
1726 * equivalent to the circle in the poloidal coordinates with 5 cells on the
1727 * cross section. This function attaches a TorusManifold to all boundary
1728 * faces which are marked with a manifold id of 1, a CylindricalManifold to
1729 * the interior cells and all their faces which are marked with a manifold
1730 * id of 2 (representing a flat state within the poloidal coordinates), and
1731 * a TransfiniteInterpolationManifold to the cells between the TorusManifold
1732 * on the surface and the ToroidalManifold in the center, with cells marked
1733 * with manifold id 0.
1734 *
1735 * An example for the case if @p dim is 3 with a cut through the domain at
1736 * $z=0$, 6 toroidal cells, $R=2$ and $r=0.5$ without any global refinement
1737 * is given here:
1738 *
1739 * @image html torus_manifold_ids.png
1740 *
1741 * In this picture, the light gray shade represents the manifold id 0 of the
1742 * transfinite interpolation, which is applied to smoothly add new points
1743 * between the toroidal shape on the domain boundary and the inner rim where
1744 * a cylindrical description around the y-axis is prescribed. The inner rim
1745 * with the manifold id 2 is shown in red shade.
1746 *
1747 * If @p dim is 2, the mesh will describe the surface of the torus and this
1748 * function attaches a TorusManifold to all cells and faces (which are
1749 * marked with a manifold id of 0).
1750 *
1751 * @param tria The triangulation to be filled.
1752 *
1753 * @param centerline_radius The radius of the circle which forms the center
1754 * line of the torus containing the loop of cells. Must be greater than @p
1755 * inner_radius.
1756 *
1757 * @param inner_radius The distance between the inner edge of the torus and
1758 * origin.
1759 *
1760 * @param n_cells_toroidal Optional argument to set the number of cell
1761 * layers in toroidal direction. The default is 6 cell layers.
1762 *
1763 * @param phi Optional argument to generate an open torus with angle
1764 * $0 < \varphi <= 2 \pi$. The default value is $2 \pi$,
1765 * in which case a closed torus is generated. If the torus is open,
1766 * the torus is cut at two planes perpendicular to the torus centerline.
1767 * The center of these two planes are located at $(x_1, y_1, z_1) = (R, 0, 0)$
1768 * and $(x_2, y_2, z_2) = (R \cos(\varphi), 0, R \sin(\varphi))$.
1769 *
1770 * @note Implemented for Triangulation<2,3> and Triangulation<3,3>.
1771 */
1772 template <int dim, int spacedim>
1773 void
1774 torus(Triangulation<dim, spacedim> &tria,
1775 const double centerline_radius,
1776 const double inner_radius,
1777 const unsigned int n_cells_toroidal = 6,
1778 const double phi = 2.0 * numbers::PI);
1779
1780 /**
1781 * This function produces a square in the <i>xy</i>-plane with a cylindrical
1782 * hole in the middle. The square and the circle are centered at the
1783 * origin. In 3d, this geometry is extruded in $z$ direction to the interval
1784 * $[0,L]$.
1785 *
1786 * The inner boundary has a manifold id of $0$ and a boundary id of
1787 * $6$. This function attaches a PolarManifold or CylindricalManifold to the
1788 * interior boundary in 2d and 3d respectively. The other faces have
1789 * boundary ids of $0, 1, 2, 3, 4$, or $5$ given in the standard order of
1790 * faces in 2d or 3d.
1791 *
1792 * @image html cubes_hole.png
1793 *
1794 * It is implemented in 2d and 3d, and takes the following arguments:
1795 *
1796 * @param triangulation The triangulation to be filled.
1797 * @param inner_radius Radius of the internal hole.
1798 * @param outer_radius Half of the edge length of the square.
1799 * @param L Extension in @p z-direction (only used in 3d).
1800 * @param repetitions Number of subdivisions along the @p z-direction.
1801 * @param colorize Whether to assign different boundary indicators to
1802 * different faces (see
1803 * @ref GlossColorization "the glossary entry on colorization").
1804 * The colors are given in lexicographic ordering for the
1805 * flat faces (0 to 3 in 2d, 0 to 5 in 3d) plus the curved hole (4 in 2d,
1806 * and 6 in 3d). If @p colorize is set to false, then flat faces get the
1807 * number 0 and the hole gets number 1.
1808 *
1809 * @note This function is available through the python interface as
1810 * `triangulation.generate_hyper_cube_with_cylindrical_hole(inner_radius =
1811 * 0.25, outer_radius = 0.5, L = 0.5, repetitions = 1, colorize = false)`.
1812 */
1813 template <int dim, int spacedim>
1814 void
1815 hyper_cube_with_cylindrical_hole(Triangulation<dim, spacedim> &triangulation,
1816 const double inner_radius = .25,
1817 const double outer_radius = .5,
1818 const double L = .5,
1819 const unsigned int repetitions = 1,
1820 const bool colorize = false);
1821
1822 /**
1823 * Produce a grid consisting of concentric shells. The primary difference
1824 * between this function and GridGenerator::hyper_shell() is that this
1825 * function permits unevenly spaced (in the radial direction)
1826 * @ref GlossCoarseMesh "coarse level cells".
1827 *
1828 * The parameters @p center, @p inner_radius, and @p outer_radius behave in
1829 * the same way as the first three arguments to
1830 * GridGenerator::hyper_shell. @p n_shells gives the total number of shells
1831 * to use (i.e., the number of cells in the radial direction). The outer
1832 * radius of the $k$th shell is given by
1833 *
1834 * @f[
1835 * r = r_{\mathrm{inner}} + (r_\mathrm{outer} - r_\mathrm{inner})
1836 * \left(1 - \frac{ \tanh(\mathrm{skewness}(1 - k/\mathrm{n\_shells}))}
1837 * {\tanh(\mathrm{skewness})}\right)
1838 * @f]
1839 *
1840 * where @p skewness is a parameter controlling the shell spacing in the
1841 * radial direction: values of @p skewness close to zero correspond to even
1842 * spacing, while larger values of @p skewness (such as $2$ or $3$)
1843 * correspond to shells biased to the inner radius.
1844 *
1845 * @p n_cells_per_shell is the same as in GridGenerator::hyper_shell: in 2d
1846 * the default choice of zero will result in 8 cells per shell (and 12 in
1847 * 3d). The only valid values in 3d are 6 (the default), 12, and 96 cells:
1848 * see the documentation of GridGenerator::hyper_shell for more information.
1849 *
1850 * If @p colorize is <code>true</code> then the outer boundary of the merged
1851 * shells has a boundary id of $1$ and the inner boundary has a boundary id
1852 * of $0$.
1853 *
1854 * Example: The following code (see, e.g., step-10 for instructions on how
1855 * to visualize GNUPLOT output)
1856 *
1857 * @code
1858 * #include <deal.II/fe/mapping_q.h>
1859 *
1860 * #include <deal.II/grid/grid_generator.h>
1861 * #include <deal.II/grid/grid_out.h>
1862 * #include <deal.II/grid/tria.h>
1863 *
1864 * #include <fstream>
1865 *
1866 * int main()
1867 * {
1868 * using namespace dealii;
1869 *
1870 * Triangulation<2> triangulation;
1871 * GridGenerator::concentric_hyper_shells(triangulation,
1872 * Point<2>(),
1873 * 1.0,
1874 * 2.0,
1875 * 5u,
1876 * 2.0);
1877 *
1878 * GridOut grid_out;
1879 * GridOutFlags::Gnuplot gnuplot_flags(false, 10, true);
1880 * grid_out.set_flags(gnuplot_flags);
1881 *
1882 * const MappingQ<2> mapping(3);
1883 * std::ofstream out("out.gpl");
1884 * grid_out.write_gnuplot(triangulation, out, &mapping);
1885 * }
1886 * @endcode
1887 *
1888 * generates the following output:
1889 *
1890 * @image html concentric_hyper_shells_2d.svg
1891 */
1892 template <int dim>
1893 void
1894 concentric_hyper_shells(Triangulation<dim> &triangulation,
1895 const Point<dim> &center,
1896 const double inner_radius = 0.125,
1897 const double outer_radius = 0.25,
1898 const unsigned int n_shells = 1,
1899 const double skewness = 0.1,
1900 const unsigned int n_cells_per_shell = 0,
1901 const bool colorize = false);
1902
1903 /**
1904 * Produce a ring of cells in 3d that is cut open, twisted and glued
1905 * together again. This results in a kind of moebius-loop.
1906 *
1907 * @param tria The triangulation to be worked on.
1908 * @param n_cells The number of cells in the loop. Must be greater than
1909 * 4.
1910 * @param n_rotations The number of rotations ($\pi/2$ each) to be performed
1911 * before gluing the loop together.
1912 * @param R The radius of the circle, which forms the middle line
1913 * of the torus containing the loop of cells. Must be greater than @p r.
1914 * @param r The radius of the cylinder bent together as a loop.
1915 */
1916 void
1917 moebius(Triangulation<3, 3> &tria,
1918 const unsigned int n_cells,
1919 const unsigned int n_rotations,
1920 const double R,
1921 const double r);
1922
1923 /**
1924 * Call one of the other GridGenerator functions, parsing the name of the
1925 * function to call from the string @p grid_generator_function_name, and
1926 * the arguments to the function from the string
1927 * @p grid_generator_function_arguments.
1928 *
1929 * The string that supplies the arguments is passed to the function
1930 * Patterns::Tools::Convert<TupleType>::to_value(), where `TupleType` here is
1931 * a tuple containing **all** the arguments of the GridGenerator function,
1932 * including all optional arguments.
1933 *
1934 * An example usage of this function is given by:
1935 * @code
1936 * GridGenerator::generate_from_name_and_arguments(
1937 * tria,
1938 * "hyper_ball",
1939 * "0.0, 0.0 : 1 : false");
1940 * @endcode
1941 * Here, the colon separates the function arguments, and the comma separates
1942 * the coordinates of a Point<2> argument.
1943 *
1944 * According to the arity of the `TupleType`, the arguments of the function
1945 * may be separated by different separators (see the documentation of
1946 * Patterns::Tuple for the details of how the conversion is
1947 * performed). If a wrong format is used, an exception is thrown, and the
1948 * expected format is output as an error message.
1949 *
1950 * All GridGenerator functions are supported. If you find some that are
1951 * missing, please open an issue on GitHub.
1952 *
1953 * @param tria The triangulation to be worked on
1954 * @param grid_generator_function_name The name of the function to call
1955 * @param grid_generator_function_arguments The arguments of the function, in
1956 * the format of a tuple-convertible string
1957 */
1958 template <int dim, int spacedim>
1959 void
1960 generate_from_name_and_arguments(
1961 Triangulation<dim, spacedim> &tria,
1962 const std::string &grid_generator_function_name,
1963 const std::string &grid_generator_function_arguments);
1964
1965 /**
1966 * Generate a Triangulation from the zero level set of an implicit function,
1967 * using the CGAL library.
1968 *
1969 * This function is only implemented for `dim` equal to two or three, and
1970 * requires that deal.II is configured using `DEAL_II_WITH_CGAL`. When `dim`
1971 * is equal to three, the @p implicit_function is supposed to be negative in
1972 * the interior of the domain, positive outside, and to be entirely enclosed
1973 * in a ball of radius @p outer_ball_radius centered at the point
1974 * @p interior_point. The triangulation that is generated covers the volume
1975 * bounded by the zero level set of the implicit function where the
1976 * @p implicit_function is negative.
1977 *
1978 * When `dim` is equal to two, the generated surface triangulation is the zero
1979 * level set of the @p implicit_function, oriented such that the surface
1980 * triangulation has normals pointing towards the region where
1981 * @p implicit_function is positive.
1982 *
1983 * The struct @p data can be used to pass additional
1984 * arguments to the CGAL::Mesh_criteria_3 class (see
1985 * https://doc.cgal.org/latest/Mesh_3/index.html for more information.)
1986 *
1987 * An example usage of this function is given by
1988 *
1989 * @code
1990 * Triangulation<dim, 3> tria;
1991 * FunctionParser<3> my_function("(1-sqrt(x^2+y^2))^2+z^2-.25");
1992 * GridGenerator::implicit_function( tria, my_function,
1993 * Point<3>(.5, 0, 0), 1.0, cell_size = 0.2);
1994 * @endcode
1995 *
1996 * The above snippet of code generates the following grid for `dim` equal to
1997 * two and three respectively
1998 *
1999 * @image html grid_generator_implicit_function_2d.png
2000 *
2001 * @image html grid_generator_implicit_function_3d.png
2002 *
2003 * Also see
2004 * @ref simplex "Simplex support".
2005 *
2006 * @param[out] tria The output triangulation
2007 * @param[in] implicit_function The implicit function
2008 * @param[in] data Additional parameters to pass to the CGAL::make_mesh_3
2009 * function and to the CGAL::make_surface_mesh functions
2010 * @param[in] interior_point A point in the interior of the domain, for which
2011 * @p implicit_function is negative
2012 * @param[in] outer_ball_radius The radius of the ball that will contain the
2013 * generated Triangulation object
2014 */
2015 template <int dim>
2016 void
2017 implicit_function(Triangulation<dim, 3> &tria,
2018 const Function<3> &implicit_function,
2019 const CGALWrappers::AdditionalData<dim> &data =
2020 CGALWrappers::AdditionalData<dim>{},
2021 const Point<3> &interior_point = Point<3>(),
2022 const double &outer_ball_radius = 1.0);
2023
2024 /**
2025 * Create a deal.II Triangulation<3> out of a deal.II Triangulation<2,3>
2026 * by filling it with tetrahedra.
2027 *
2028 * The last optional argument @p data can be used to pass additional
2029 * arguments to the CGAL::Mesh_criteria_3 class (see
2030 * https://doc.cgal.org/latest/Mesh_3/index.html for more information).
2031 *
2032 *
2033 * @param [in] surface_tria The input deal.II Triangulation<2,3>.
2034 * @param [out] vol_tria The output deal.II Triangulation<3>.
2035 * @param[in] data Additional parameters to pass to the CGAL::make_mesh_3
2036 * function.
2037 */
2038 void
2039 surface_mesh_to_volumetric_mesh(const Triangulation<2, 3> &surface_tria,
2040 Triangulation<3> &vol_tria,
2041 const CGALWrappers::AdditionalData<3> &data =
2042 CGALWrappers::AdditionalData<3>{});
2043 /** @} */
2044
2045 /**
2046 * @name Creating meshes from other meshes
2047 */
2048 /** @{ */
2049
2050 /**
2051 * Given the two triangulations specified as the first two arguments, create
2052 * the triangulation that contains the cells of both triangulation and store
2053 * it in the third parameter. Previous content of @p result will be deleted.
2054 * One of the two input triangulations can also be the @p result triangulation.
2055 *
2056 * This function is most often used to compose meshes for more complicated
2057 * geometries if the geometry can be composed of simpler parts for which
2058 * functions exist to generate
2059 * @ref GlossCoarseMesh "coarse meshes".
2060 * For example, the channel mesh
2061 * used in step-35 could in principle be created using a mesh created by the
2062 * GridGenerator::hyper_cube_with_cylindrical_hole function and several
2063 * rectangles, and merging them using the current function. The rectangles
2064 * will have to be translated to the right for this, a task that can be done
2065 * using the GridTools::shift function (other tools to transform individual
2066 * mesh building blocks are GridTools::transform, GridTools::rotate, and
2067 * GridTools::scale).
2068 *
2069 * Vertices that are less than @p duplicated_vertex_tolerance apart will be merged
2070 * together. It is usually necessary to set this value to something that
2071 * depends on the input triangulations in some way. One reasonable choice is
2072 * to use the minimum distance between all adjacent vertices of the input
2073 * mesh divided by some constant:
2074 *
2075 * @code
2076 * auto min_line_length = [](const Triangulation<dim> &tria) -> double
2077 * {
2078 * double length = std::numeric_limits<double>::max();
2079 * for (const auto &cell : tria.active_cell_iterators())
2080 * for (const auto n : cell->line_indices())
2081 * length = std::min(length, (cell->line(n)->vertex(0) -
2082 * cell->line(n)->vertex(1)).norm());
2083 * return length;
2084 * };
2085 *
2086 * const double tolerance = std::min(min_line_length(triangulation_1),
2087 * min_line_length(triangulation_2)) / 2.0;
2088 * @endcode
2089 *
2090 * This will merge any vertices that are closer than any pair of vertices on
2091 * the input meshes. If the tolerance is set to zero, vertices are not merged.
2092 *
2093 * @note The two input triangulations must be
2094 * @ref GlossCoarseMesh "coarse meshes",
2095 * i.e., they can not have any
2096 * refined cells.
2097 *
2098 * @note The function copies the material ids of the cells of the two input
2099 * triangulations into the output triangulation. If @p copy_manifold_ids is
2100 * set to @p true, manifold ids will be copied. If @p copy_boundary_ids is
2101 * set to @p true, boundary_ids are copied to all remaining faces at the boundary.
2102 *
2103 * @note This function does not attach any manifolds to @p result, nor does
2104 * it set any manifold ids. In particular, manifolds attached to the two
2105 * input triangulations will be lost in the @p result triangulation.
2106 *
2107 * @note For a related operation on refined meshes when both meshes are
2108 * derived from the same coarse mesh, see
2109 * GridGenerator::create_union_triangulation().
2110 */
2111 template <int dim, int spacedim>
2112 void
2113 merge_triangulations(const Triangulation<dim, spacedim> &triangulation_1,
2114 const Triangulation<dim, spacedim> &triangulation_2,
2115 Triangulation<dim, spacedim> &result,
2116 const double duplicated_vertex_tolerance = 1.0e-12,
2117 const bool copy_manifold_ids = false,
2118 const bool copy_boundary_ids = false);
2119
2120 /**
2121 * Same as above but allows to merge more than two triangulations at once.
2122 * The following gives an example of how to use this function:
2123 * @code
2124 * Triangulation<2> tria_1, tria_2, tria_3;
2125 * // initialize tria_1, tria_2 and tria_3
2126 * ...
2127 * Triangulation<2> merged_triangulation;
2128 * GridGenerator::merge_triangulations({&tria_1, &tria_2, &tria_3},
2129 * merged_triangulation,
2130 * 1.0e-10,
2131 * false,
2132 * false);
2133 * @endcode
2134 *
2135 * @note This function is available through the python interface as
2136 * `result.merge_triangulations(triangulations, duplicated_vertex_tolerance =
2137 * 1e-12, copy_manifold_ids = false)`.
2138 */
2139 template <int dim, int spacedim>
2140 void
2141 merge_triangulations(
2142 const std::vector<const Triangulation<dim, spacedim> *> &triangulations,
2143 Triangulation<dim, spacedim> &result,
2144 const double duplicated_vertex_tolerance = 1.0e-12,
2145 const bool copy_manifold_ids = false,
2146 const bool copy_boundary_ids = false);
2147
2148 /**
2149 * \brief Replicate a given triangulation in multiple coordinate axes
2150 *
2151 * @param input The triangulation which will be replicated along the
2152 * coordinate axes.
2153 *
2154 * @param extents A vector with <tt>dim</tt> entries specifying how many
2155 * copies of a triangulation should be present along each coordinate axis.
2156 *
2157 * @param result The triangulation to be created. It needs to be empty upon
2158 * calling this function.
2159 *
2160 * This function creates a new Triangulation equal to a
2161 * <tt>dim</tt>-dimensional array of copies of @p input. Copies of @p input
2162 * are created by translating @p input along the coordinate axes. Boundary
2163 * ids of faces (but not lines in 3d) and all manifold ids are copied but
2164 * Manifold objects are not since most Manifold objects do not work
2165 * correctly when a Triangulation has been translated.
2166 *
2167 * To see how this works, consider the following code:
2168 * @code
2169 * Triangulation<2> input;
2170 * GridGenerator::hyper_cube_with_cylindrical_hole(input);
2171 * Triangulation<2> output;
2172 * GridGenerator::replicate_triangulation(input, {3, 2}, output);
2173 * @endcode
2174 * results in
2175 *
2176 * @image html replicated_tria_2d.png
2177 *
2178 * And, similarly, in 3d:
2179 * @code
2180 * Triangulation<3> input;
2181 * GridGenerator::hyper_cross(1, 1, 1, 2, 1, 2);
2182 * Triangulation<3> output;
2183 * GridGenerator::replicate_triangulation(input, {3, 2, 1}, output);
2184 * @endcode
2185 * results in
2186 *
2187 * @image html replicated_tria_3d.png
2188 *
2189 * @note This function determines the spacing of the copies of @p input
2190 * based on the BoundingBox of @p input. If the boundary faces of @p input
2191 * are not aligned with the coordinate axes then the copies might not share
2192 * common faces; i.e., this function is intended for simple geometries with
2193 * boundary faces aligned along the coordinate axes.
2194 *
2195 * @note This function is available through the python interface as
2196 * `result.replicate_triangulation(input, extents)`.
2197 */
2198 template <int dim, int spacedim = dim>
2199 void
2200 replicate_triangulation(const Triangulation<dim, spacedim> &input,
2201 const std::vector<unsigned int> &extents,
2202 Triangulation<dim, spacedim> &result);
2203
2204 /**
2205 * Given the two triangulations specified as the first two arguments, create
2206 * the triangulation that contains the finest cells of both triangulation
2207 * and store it in the third parameter. Previous content of @p result will
2208 * be deleted.
2209 *
2210 * @note This function is intended to create an adaptively refined
2211 * triangulation that contains the <i>most refined cells</i> from two input
2212 * triangulations that were derived from the <i>same</i>
2213 * @ref GlossCoarseMesh "coarse mesh"
2214 * by
2215 * adaptive refinement. This is an operation sometimes needed when one
2216 * solves for two variables of a coupled problem on separately refined
2217 * meshes on the same domain (for example because these variables have
2218 * boundary layers in different places) but then needs to compute something
2219 * that involves both variables or wants to output the result into a single
2220 * file. In both cases, in order not to lose information, the two solutions
2221 * can not be interpolated onto the respectively other mesh because that may
2222 * be coarser than the ones on which the variable was computed. Rather, one
2223 * needs to have a mesh for the domain that is at least as fine as each of
2224 * the two initial meshes. This function computes such a mesh.
2225 *
2226 * @note If you want to create a mesh that is the merger of two other
2227 * @ref GlossCoarseMesh "coarse meshes",
2228 * for example in order to compose
2229 * a mesh for a complicated geometry
2230 * from meshes for simpler geometries, then this is not the function for
2231 * you. Instead, consider GridGenerator::merge_triangulations().
2232 *
2233 * @note This function assumes that both @p triangulation_1 and @p
2234 * triangulation_2 have the same manifold descriptions. The output
2235 * Triangulation @p has the same manifold ids as these two triangulations.
2236 *
2237 * @note Both of the source conditions need to be available entirely locally.
2238 * In other words, they can not be objects of type
2239 * parallel::distributed::Triangulation.
2240 */
2241 template <int dim, int spacedim>
2242 void
2243 create_union_triangulation(
2244 const Triangulation<dim, spacedim> &triangulation_1,
2245 const Triangulation<dim, spacedim> &triangulation_2,
2246 Triangulation<dim, spacedim> &result);
2247
2248 /**
2249 * This function creates a triangulation that consists of the same cells as
2250 * are present in the first argument, except those cells that are listed in
2251 * the second argument. The purpose of the function is to generate
2252 * geometries <i>subtractively</i> from the geometry described by an
2253 * existing triangulation. A prototypical case is a 2d domain with
2254 * rectangular holes. This can be achieved by first meshing the entire
2255 * domain and then using this function to get rid of the cells that are
2256 * located at the holes. A demonstration of this particular use case is part
2257 * of step-27. Likewise, you could create the mesh that
2258 * GridGenerator::hyper_L() produces by starting with a
2259 * GridGenerator::hyper_cube(), refining it once, and then calling the
2260 * current function with a single cell in the second argument.
2261 *
2262 * @param[in] input_triangulation The original triangulation that serves as
2263 * the template from which the new one is to be created.
2264 * @param[in] cells_to_remove A list of cells of the triangulation provided
2265 * as first argument that should be removed (i.e., that should not show up
2266 * in the result.
2267 * @param[out] result The resulting triangulation that consists of the same
2268 * cells as are in @p input_triangulation, with the exception of the cells
2269 * listed in @p cells_to_remove.
2270 *
2271 * @note Unlike most GridGenerator functions, this function does not attach
2272 * any manifolds to @p result, nor does it set any manifold ids.
2273 *
2274 * @pre Because we cannot create triangulations de novo that contain
2275 * adaptively refined cells, the input triangulation needs to have all of
2276 * its cells on the same level. Oftentimes, this will in fact be the
2277 * coarsest level, but it is allowed to pass in a triangulation that has
2278 * been refined <i>globally</i> a number of times. The output triangulation
2279 * will in that case simply be a mesh with only one level that consists of
2280 * the active cells of the input minus the ones listed in the second
2281 * argument. However, the input triangulation must not have been
2282 * <i>adaptively</i> refined.
2283 */
2284 template <int dim, int spacedim>
2285 void
2286 create_triangulation_with_removed_cells(
2287 const Triangulation<dim, spacedim> &input_triangulation,
2288 const std::set<typename Triangulation<dim, spacedim>::active_cell_iterator>
2289 &cells_to_remove,
2290 Triangulation<dim, spacedim> &result);
2291
2292 /**
2293 * Extrude the Triangulation @p input in the $z$ direction from $z = 0$ to $z =
2294 * \text{height}$ and store it in @p result. This is done by replicating the
2295 * input triangulation `n_slices` times in $z$ direction, and then forming
2296 * `(n_slices-1)` layers of cells out of these replicates.
2297 *
2298 * The boundary indicators of the faces of @p input will be assigned to
2299 * the corresponding side walls in $z$ direction. The bottom and top get the
2300 * next two free boundary indicators: i.e., if @p input has boundary ids of
2301 * $0$, $1$, and $42$, then the $z = 0$ boundary id of @p result will be $43$
2302 * and the $z = \text{height}$ boundary id will be $44$.
2303 *
2304 * This function does not, by default, copy manifold ids. The reason for
2305 * this is that there is no way to set the manifold ids on the lines of the
2306 * resulting Triangulation without more information: for example, if two
2307 * faces of @p input with different manifold ids meet at a shared vertex then
2308 * there is no <em>a priori</em> reason to pick one manifold id or another
2309 * for the lines created in @p result that are parallel to the $z$-axis and
2310 * pass through that point. If @p copy_manifold_ids is <code>true</code>
2311 * then this function sets line manifold ids by picking the one that appears
2312 * <em>first</em> in @p manifold_priorities. For example: if @p
2313 * manifold_priorities is <code>{0, 42, numbers::flat_manifold_id}</code>
2314 * and the line under consideration is adjacent to faces with manifold ids of
2315 * <code>0</code> and <code>42</code>, then that line will have a manifold id
2316 * of <code>0</code>. The correct ordering is almost always
2317 * <ol>
2318 * <li>manifold ids set on the boundary,</li>
2319 * <li>manifold ids that describe most of the cells in the Triangulation
2320 * (e.g., numbers::flat_manifold_id), and</li>
2321 * <li>any manifold ids corresponding to TransfiniteInterpolationManifold
2322 * manifolds.</li>
2323 * </ol>
2324 *
2325 * In particular, since TransfiniteInterpolationManifold interpolates
2326 * between surrounding manifolds, its manifold id should usually not be set
2327 * on lines or faces that are adjacent to cells with different manifold
2328 * ids. The default value for @p manifold_priorities follows this ranking
2329 * (where each category is sorted in ascending order):
2330 * <ol>
2331 * <li>manifold ids associated with manifolds that are not
2332 * TransfiniteInterpolationManifold, and</li>
2333 * <li>manifold ids associated with any TransfiniteInterpolationManifold
2334 * objects.</li>
2335 * </ol>
2336 * Note that numbers::flat_manifold_id (should it be a manifold id of @p
2337 * input) will always be the last entry in the first category.
2338 *
2339 * @param[in] input A two-dimensional input triangulation.
2340 * @param[in] n_slices The number of times the input triangulation will
2341 * be replicated in $z$ direction. These slices will then be connected
2342 * into `(n_slices-1)` layers of three-dimensional cells. Clearly,
2343 * `n_slices` must be at least two.
2344 * @param[in] height The distance in $z$ direction between the individual
2345 * slices.
2346 * @param[out] result The resulting three-dimensional triangulation.
2347 * @param[in] copy_manifold_ids See the description above.
2348 * @param[in] manifold_priorities See the description above.
2349 *
2350 * @pre The 2d input triangulation @p input must be a
2351 * @ref GlossCoarseMesh "coarse mesh",
2352 * i.e., it cannot have any
2353 * refined cells.
2354 *
2355 * @note Since @p input and @p output have different spatial dimensions, no
2356 * manifold objects are copied by this function regardless of the value of
2357 * @p copy_manifold_ids.
2358 *
2359 * @note This function is available through the python interface as
2360 * `input.extrude_triangulation(n_slices, height, result)`.
2361 */
2362 void
2363 extrude_triangulation(
2364 const Triangulation<2, 2> &input,
2365 const unsigned int n_slices,
2366 const double height,
2367 Triangulation<3, 3> &result,
2368 const bool copy_manifold_ids = false,
2369 const std::vector<types::manifold_id> &manifold_priorities = {});
2370
2371 /**
2372 * Overload of extrude_triangulation() to allow dimension independent
2373 * code to compile. This function throws an error when called, as
2374 * extrude_triangulation() is only implemented to extrude a dim=2 to a dim=3
2375 * Triangulation.
2376 */
2377 void
2378 extrude_triangulation(
2379 const Triangulation<2, 2> &input,
2380 const unsigned int n_slices,
2381 const double height,
2382 Triangulation<2, 2> &result,
2383 const bool copy_manifold_ids = false,
2384 const std::vector<types::manifold_id> &manifold_priorities = {});
2385
2386
2387 /**
2388 * Overload of the previous function. Take a 2d Triangulation that is being
2389 * extruded. Differing from the previous function taking height and number of
2390 * slices for uniform extrusion, this function takes z-axis values
2391 * @p slice_coordinates where the slicing will happen. The boundary indicators
2392 * of the faces of @p input are going to be assigned to the corresponding side
2393 * walls in z direction. The bottom and top get the next two free boundary
2394 * indicators.
2395 *
2396 * @pre The 2d input triangulation @p input must be a
2397 * @ref GlossCoarseMesh "coarse mesh",
2398 * i.e., it cannot have any
2399 * refined cells.
2400 *
2401 * @note Since @p input and @p output have different spatial dimensions no
2402 * manifold objects are copied (nor are any manifold ids set) by this
2403 * function.
2404 */
2405 void
2406 extrude_triangulation(
2407 const Triangulation<2, 2> &input,
2408 const std::vector<double> &slice_coordinates,
2409 Triangulation<3, 3> &result,
2410 const bool copy_manifold_ids = false,
2411 const std::vector<types::manifold_id> &manifold_priorities = {});
2412
2413 /**
2414 * Overload of extrude_triangulation() to allow dimension independent
2415 * code to compile. This function throws an error when called, as
2416 * extrude_triangulation() is only implemented to extrude a dim=2 to a dim=3
2417 * Triangulation.
2418 */
2419 void
2420 extrude_triangulation(
2421 const Triangulation<2, 2> &input,
2422 const std::vector<double> &slice_coordinates,
2423 Triangulation<2, 2> &result,
2424 const bool copy_manifold_ids = false,
2425 const std::vector<types::manifold_id> &manifold_priorities = {});
2426
2427
2428
2429 /**
2430 * Given an input triangulation @p in_tria, this function makes a new flat
2431 * triangulation @p out_tria which contains a single level with all active
2432 * cells of the input triangulation. If @p spacedim1 and @p spacedim2 are
2433 * different, only the first few components of the vertex coordinates are
2434 * copied over. This is useful to create a Triangulation<2,3> out of a
2435 * Triangulation<2,2>, or to project a Triangulation<2,3> into a
2436 * Triangulation<2,2>, by neglecting the $z$ components of the vertices.
2437 *
2438 * No internal checks are performed on the vertices, which are assumed to
2439 * make sense topologically in the target @p spacedim2 dimensional space. If
2440 * this is not the case, you will encounter problems when using the
2441 * triangulation later on.
2442 *
2443 * All information about cell
2444 * @ref GlossManifoldIndicator "manifold indicators"
2445 * and
2446 * @ref GlossMaterialId "material indicators"
2447 * are copied from
2448 * one triangulation to the other. The same is true for the manifold
2449 * indicators and, if an object is at the boundary, the boundary
2450 * indicators of faces and edges of the triangulation.
2451 *
2452 * This function will fail if the input Triangulation is of type
2453 * parallel::distributed::Triangulation, as well as when the input
2454 * Triangulation contains hanging nodes. In other words, this function
2455 * only works for globally refined triangulations.
2456 *
2457 * @param[in] in_tria The base input for a new flat triangulation.
2458 * @param[out] out_tria The desired flattened triangulation constructed from
2459 * the in_tria.
2460 *
2461 * @note Since @p input and @p output have different spatial dimensions, no
2462 * manifold objects are copied by this function: you must attach new
2463 * manifold objects to @p out_tria.
2464 *
2465 * @note This function is available through the python interface as
2466 * `in_tria.flatten_triangulation(out_tria)`.
2467 */
2468 template <int dim, int spacedim1, int spacedim2>
2469 void
2470 flatten_triangulation(const Triangulation<dim, spacedim1> &in_tria,
2471 Triangulation<dim, spacedim2> &out_tria);
2472
2473 /**
2474 * Convert a triangulation consisting only of hypercube cells
2475 * (quadrilaterals, hexahedra) to a triangulation only consisting of
2476 * simplices (triangles, tetrahedra).
2477 *
2478 * The default splitting algorithm creates (in 2d) eight triangles for each
2479 * quadrilateral and (in 3d) 24 tetrahedra for each hexahedron. These splits
2480 * avoid creating mesh anisotropies by connecting the midpoint of each face to
2481 * a vertex of that face. These values are encoded in the default value of @p
2482 * n_divisions.
2483 *
2484 * Alternatively, one may split each quadrilateral into two triangles (by
2485 * adding a line between vertex 1 and vertex 2) and each hexahedron into six
2486 * tetrahedra (by adding a line between vertex 0 and vertex 7) by setting
2487 * @p n_divisions to 2 or 6, respectively.
2488 *
2489 * As an example, the following image shows how a set of four hexahedra
2490 * meshing one eighth of a sphere are subdivided into tetrahedra, and how
2491 * the curved surface is taken into account. Colors indicate how boundary
2492 * indicators are inherited:
2493 * @image html "convert_hypercube_to_simplex_mesh_visualization_octant.png"
2494 *
2495 * @image html "convert_hypercube_to_simplex_mesh_visualization.png"
2496 *
2497 * Material ID and boundary IDs are inherited upon conversion.
2498 *
2499 * @param[in] in_tria The triangulation containing quadrilateral or
2500 * hexahedral elements.
2501 *
2502 * @param[out] out_tria The converted triangulation containing triangular or
2503 * tetrahedral elements.
2504 *
2505 * @param[in] n_divisions The number of divisions for each hypercube cell.
2506 * Must be either 2 or 8 (the default) in 2d or 6 or 24 (the default) in 3d.
2507 *
2508 * @note No manifold objects are copied by this function: you must
2509 * copy existing manifold objects from @p in_tria to @p out_tria, e.g.,
2510 * with the following code:
2511 * @code
2512 * for (const auto i : in_tria.get_manifold_ids())
2513 * if (i != numbers::flat_manifold_id)
2514 * out_tria.set_manifold(i, in_tria.get_manifold(i));
2515 * @endcode
2516 *
2517 * Also see
2518 * @ref simplex "Simplex support".
2519 *
2520 * @note This function is available through the python interface as
2521 * `in_tria.convert_hypercube_to_simplex_mesh(out_tria)`.
2522 *
2523 * @note in 1d this function copies @p in_tria into @p out_tria since 1d
2524 * elements (lines) are both hypercubes and simplices.
2525 */
2526 template <int dim, int spacedim>
2527 void
2528 convert_hypercube_to_simplex_mesh(const Triangulation<dim, spacedim> &in_tria,
2529 Triangulation<dim, spacedim> &out_tria,
2530 const unsigned int n_divisions = (dim == 2 ?
2531 8u :
2532 24u));
2533
2534 /**
2535 * Perform an Alfeld split (also called barycentric refinement) of a simplex
2536 * mesh.
2537 *
2538 * Each simplex cell in the input mesh (given in @p in_tria) is refined into
2539 * three (for @p dim = 2) or four (for @p dim = 3) simplices connecting to the
2540 * barycenter, which is the only new vertex added for each input cell. In the
2541 * process, the simplex mesh is flattened (no hierarchy is kept).
2542 *
2543 * @note Currently only implemented for @p dim = 2 and hanging nodes are not
2544 * supported.
2545 *
2546 * @image html alfeld-split.svg
2547 *
2548 * The meshes produced by this function can be used for Scott-Vogelius
2549 * elements for the Stokes equation: The $P_k - DGP_{k-1}$ element is
2550 * point-wise divergence free on barycentric refined meshes for $k\geq 2$
2551 * for @p dim = 2 and $k\geq 3$ for @p dim = 3, see @cite Farrell2021.
2552 *
2553 * Also see
2554 * @ref simplex "Simplex support".
2555 */
2556 template <int dim, int spacedim>
2557 void
2558 alfeld_split_of_simplex_mesh(const Triangulation<dim, spacedim> &in_tria,
2559 Triangulation<dim, spacedim> &out_tria);
2560
2561 /**
2562 * Namespace Airfoil contains classes and functions in order to create a
2563 * C-type mesh for the (flow) field around Joukowski or NACA airfoils.
2564 */
2565 namespace Airfoil
2566 {
2567 /**
2568 * AdditionalData collects all settings that are required to generate a
2569 * airfoil triangulation with the functions Airfoil::create_triangulation().
2570 */
2571 struct AdditionalData
2572 {
2573 /**
2574 * Type of the airfoil: either "NACA" or "Joukowksi" to choose airfoil
2575 * geometry among NACA and Joukowski airfoil.
2576 */
2577 std::string airfoil_type;
2578
2579 /**
2580 * NACA serial number defining the airfoil shape.
2581 *
2582 * @note Currently serial numbers with length 4 are supported.
2583 * A good overview of NACA serial numbers is presented in Wikipedia
2584 * (https://en.wikipedia.org/wiki/NACA_airfoil)
2585 */
2586 std::string naca_id;
2587
2588 /**
2589 * Center of Joukowski circle.
2590 *
2591 * @note A center on the x-axis leads to a symmetrical airfoil.
2592 */
2593 Point<2, double> joukowski_center;
2594
2595 /**
2596 * Chord length of the airfoil, i.e. distance from leading to trailing
2597 * edge.
2598 */
2599 double airfoil_length;
2600
2601 /**
2602 * Vertical distance from airfoil chord to upper boundary of the mesh
2603 * i.e. half of the total mesh height.
2604 */
2605 double height;
2606
2607 /**
2608 * Length of mesh from the airfoil trailing edge to outflow boundary.
2609 */
2610 double length_b2;
2611
2612 /**
2613 * Factor defining the inclination HG of the coarse grid
2614 * The figure shows the upper coarse grid with two different inclinations
2615 * - incline_factor = 0 --> face HG
2616 * - incline_factor = 0.5 --> face HG'
2617 * Coordinate of point G' is defined by incline_factor after interpolation
2618 * G'(0) = G(0) + incline_factor * (K(0) - G(0))
2619 * with incline_factor in [0,1).
2620 *
2621 * o-----G---G'--K
2622 * / | | / |
2623 * / o | / |
2624 * / / \ |/ |
2625 * o----o H-------o
2626 */
2627 double incline_factor;
2628
2629 /**
2630 * Factor to receive a finer mesh around the airfoil by increasing
2631 * bias_factor b.
2632 * Bias function: f(x) = tanh(bx) / tanh(x) with x in [0,1], leads to a
2633 * compression of values close to x = 1.
2634 */
2635 double bias_factor;
2636
2637 /**
2638 * Number of global refinements.
2639 */
2640 unsigned int refinements;
2641
2642 /**
2643 * Number of subdivisions along the airfoil in left block.
2644 */
2645 unsigned int n_subdivision_x_0;
2646
2647 /**
2648 * Number of subdivisions along the airfoil in middle block.
2649 */
2650 unsigned int n_subdivision_x_1;
2651
2652 /**
2653 * Number of subdivisions in block right of the airfoil.
2654 */
2655 unsigned int n_subdivision_x_2;
2656
2657 /**
2658 * Number of subdivisions normal to the airfoil contour.
2659 */
2660 unsigned int n_subdivision_y;
2661
2662 /**
2663 * Factor to enhance the approximation of the airfoil geometry that
2664 * happens when interpolating provided nonequidistant airfoil points to
2665 * equidistant airfoil points. When generating the required vector
2666 * consisting the equidistant airfoil points, it is interpolated between
2667 * nonequidistand airfoil points.
2668 * Increasing the provided nonequidistant airfoil points leads to
2669 * a better approximation of the airfoil geometry. Parameter
2670 * "airfoil_sampling_factor" thereby defines the relation of
2671 * provided_nonequidistant_points to required_equidistant_points.
2672 */
2673 unsigned int airfoil_sampling_factor;
2674
2675 /**
2676 * Constructor.
2677 */
2678 AdditionalData();
2679
2680 /**
2681 * This function adds the ParameterHandler entries.
2682 *
2683 * @param[in] prm Parameter handler.
2684 */
2685 void
2686 add_parameters(ParameterHandler &prm);
2687 };
2688
2689 /**
2690 * Initialize the given triangulation with a flow field around an airfoil,
2691 * i.e., a mesh of C-Type approximating Joukowski or NACA (4 digit)
2692 * airfoils.
2693 *
2694 * The user can specify the airfoil geometry and the mesh setup by providing
2695 * input parameters for the struct AdditionalData.
2696 * Thereby, the user can choose among different types of Joukowski or NACA
2697 * airfoils with variable chord length, far field size and mesh density.
2698 *
2699 * @note This function creates a refined mesh (number of global refinements
2700 * can be specified by the user). No manifold is attached. The
2701 * vertices in the final mesh are moved by this function to the
2702 * right position.
2703 *
2704 * @note This function is currently only implemented for 2d but the mesh
2705 * can of course be extruded into the third dimension using
2706 * GridGenerator::extrude().
2707 *
2708 * @param[out] tria The triangulation to be created. It needs to be empty
2709 * upon calling this function.
2710 * @param[in] additional_data Configuration of the mesh.
2711 *
2712 \htmlonly <style>div.image
2713 *
2714 img[src="https://www.dealii.org/images/grids/airfoils_naca_joukowski.png"]{width:50%;}</style>
2715 \endhtmlonly
2716 * @image html https://www.dealii.org/images/grids/airfoils_naca_joukowski.png
2717 */
2718 template <int dim>
2719 void
2720 create_triangulation(
2721 Triangulation<dim, dim> &tria,
2722 const AdditionalData &additional_data = AdditionalData());
2723
2724
2725
2726 /**
2727 * The same as above but periodic boundary conditions on the
2728 * upper and lower faces of the far field are applied.
2729 *
2730 * @note This function is currently only implemented for 2d.
2731 *
2732 * @param[out] tria The triangulation to be created. It needs to be empty
2733 * upon calling this function.
2734 * @param[out] periodic_faces Periodic faces at upper and lower horizontal
2735 * boundaries.
2736 * @param[in] additional_data Configuration of the mesh.
2737 */
2738 template <int dim>
2739 void
2740 create_triangulation(
2741 Triangulation<dim, dim> &tria,
2742 std::vector<GridTools::PeriodicFacePair<
2743 typename Triangulation<dim, dim>::cell_iterator>> &periodic_faces,
2744 const AdditionalData &additional_data = AdditionalData());
2745
2746 } // namespace Airfoil
2747
2748 /**
2749 * Create a coordinate-parallel brick from the two diagonally opposite
2750 * corner points @p p1 and @p p2 and subdivide each cell into simplices.
2751 *
2752 * The number of vertices in coordinate
2753 * direction @p i is given by <tt>repetitions[i]+1</tt>.
2754 *
2755 * @note This function takes the mesh produced by subdivided_hyper_rectangle()
2756 * and further subdivides each cell into 2 triangles (for @p dim 2) or
2757 * 5 tetrahedra (for @p dim 3), respectively.
2758 *
2759 * @note Currently, this function only works for `dim==spacedim`.
2760 *
2761 * Also see
2762 * @ref simplex "Simplex support".
2763 */
2764 template <int dim, int spacedim>
2765 void
2766 subdivided_hyper_rectangle_with_simplices(
2767 Triangulation<dim, spacedim> &tria,
2768 const std::vector<unsigned int> &repetitions,
2769 const Point<dim> &p1,
2770 const Point<dim> &p2,
2771 const bool colorize = false);
2772
2773 /**
2774 * Initialize the given triangulation with a hypercube (square in 2d and
2775 * cube in 3d) consisting of @p repetitions cells in each direction with
2776 * each cell divided into simplices.
2777 *
2778 * The hypercube volume is the tensor product interval
2779 * $[left,right]^{\text{dim}}$ in the present number of dimensions, where
2780 * the limits are given as arguments. They default to zero and unity, then
2781 * producing the unit hypercube.
2782 *
2783 * @note This function takes the mesh produced by subdivided_hyper_cube()
2784 * and further subdivides each cell into 2 triangles (for @p dim 2) or
2785 * 5 tetrahedra (for @p dim 3), respectively.
2786 *
2787 * Also see
2788 * @ref simplex "Simplex support".
2789 */
2790 template <int dim, int spacedim>
2791 void
2792 subdivided_hyper_cube_with_simplices(Triangulation<dim, spacedim> &tria,
2793 const unsigned int repetitions,
2794 const double p1 = 0.0,
2795 const double p2 = 1.0,
2796 const bool colorize = false);
2797
2798 /** @} */
2799
2800 /**
2801 * @name Creating lower-dimensional meshes
2802 *
2803 * Created from parts of higher-dimensional meshes.
2804 */
2805 /** @{ */
2806
2807 #ifdef _MSC_VER
2808 // Microsoft's VC++ has a bug where it doesn't want to recognize that
2809 // an implementation (definition) of the extract_boundary_mesh function
2810 // matches a declaration. This can apparently only be avoided by
2811 // doing some contortion with the return type using the following
2812 // intermediate type. This is only used when using MS VC++ and uses
2813 // the direct way of doing it otherwise
2814 template <template <int, int> class MeshType, int dim, int spacedim>
2815 DEAL_II_CXX20_REQUIRES(
2816 (concepts::is_triangulation_or_dof_handler<MeshType<dim, spacedim>>))
2817 struct ExtractBoundaryMesh
2818 {
2819 using return_type =
2820 std::map<typename MeshType<dim - 1, spacedim>::cell_iterator,
2821 typename MeshType<dim, spacedim>::face_iterator>;
2822 };
2823 #endif
2824
2825 /**
2826 * This function implements a boundary subgrid extraction. Given a
2827 * <dim,spacedim>-Triangulation (the "volume mesh") the function extracts a
2828 * subset of its boundary (the "surface mesh"). The boundary to be
2829 * extracted is specified by a list of boundary_ids. If none is specified
2830 * the whole boundary will be extracted. The function is used in step-38.
2831 *
2832 * The function also builds a mapping linking the cells on the surface mesh
2833 * to the corresponding faces on the volume one. This mapping is the return
2834 * value of the function.
2835 *
2836 * @note The function builds the surface mesh by creating a
2837 * @ref GlossCoarseMesh "coarse mesh"
2838 * from
2839 * the selected faces of the coarse cells of the volume mesh. It copies the
2840 * boundary indicators of these faces to the cells of the coarse surface
2841 * mesh. The surface mesh is then refined in the same way as the faces of
2842 * the volume mesh are. In order to ensure that the surface mesh has the
2843 * same vertices as the volume mesh, it is therefore important that you
2844 * assign appropriate boundary descriptions through
2845 * Triangulation::set_manifold() to the surface mesh object before calling
2846 * this function. If you don't, the refinement will happen under the
2847 * assumption that all faces are straight (i.e using the FlatManifold class)
2848 * rather than utilizing the Manifold object you may want to use to determine
2849 * the location of new vertices.
2850 *
2851 * @tparam MeshType A type that satisfies the requirements of the
2852 * @ref ConceptMeshType "MeshType concept".
2853 * The map that is returned will be between cell iterators pointing into the
2854 * container describing the surface mesh and face iterators of the volume
2855 * mesh container. If MeshType is DoFHandler, then the function will re-build
2856 * the triangulation underlying the second argument and return a map between
2857 * appropriate iterators into the MeshType arguments. However, the function
2858 * will not actually distribute degrees of freedom on this newly created
2859 * surface mesh.
2860 *
2861 * @tparam dim The dimension of the cells of the volume mesh. For example,
2862 * if dim==2, then the cells are quadrilaterals that either live in the
2863 * plane, or form a surface in a higher-dimensional space. The dimension of
2864 * the cells of the surface mesh is consequently dim-1.
2865 * @tparam spacedim The dimension of the space in which both the volume and
2866 * the surface mesh live.
2867 *
2868 * @param[in] volume_mesh A container of cells that define the volume mesh.
2869 * @param[out] surface_mesh A container whose associated triangulation will
2870 * be built to consist of the cells that correspond to the (selected portion
2871 * of) the boundary of the volume mesh.
2872 * @param[in] boundary_ids A list of boundary indicators denoting that
2873 * subset of faces of volume cells for which this function should extract
2874 * the surface mesh. If left at its default, i.e., if the set is empty, then
2875 * the function operates on <i>all</i> boundary faces.
2876 *
2877 * To prevent printing a very long type in the doxygen documentation the
2878 * actual return type of this function is
2879 *
2880 * @code
2881 * std::map<typename DoFHandler<dim - 1, spacedim>::cell_iterator,
2882 * typename DoFHandler<dim, spacedim>::face_iterator>
2883 * @endcode
2884 *
2885 * when <tt>MeshType</tt> is DoFHandler and
2886 *
2887 * @code
2888 * std::map<typename Triangulation<dim - 1, spacedim>::cell_iterator,
2889 * typename Triangulation<dim, spacedim>::face_iterator>
2890 * @endcode
2891 *
2892 * when <tt>MeshType</tt> is Triangulation and and not the shorter stub
2893 * provided here.
2894 *
2895 * @return A map that for each cell of the surface mesh (key) returns an
2896 * iterator to the corresponding face of a cell of the volume mesh (value).
2897 * The keys include both active and non-active cells of the surface mesh.
2898 * The order of vertices of surface cells and the corresponding
2899 * volume faces may not match in order to ensure that each surface cell is
2900 * associated with an outward facing normal.
2901 * As a consequence, if you want to match quantities on the faces of the
2902 * domain cells and on the cells of the surface mesh, you may have to
2903 * translate between vertex locations or quadrature points.
2904 *
2905 * @note The algorithm outlined above assumes that all faces on higher
2906 * refinement levels always have exactly the same boundary indicator as
2907 * their parent face. Consequently, we can start with coarse level faces and
2908 * build the surface mesh based on that. It would not be very difficult to
2909 * extend the function to also copy boundary indicators from finer level
2910 * faces to their corresponding surface mesh cells, for example to
2911 * accommodate different geometry descriptions in the case of curved
2912 * boundaries (but this is not currently implemented).
2913 *
2914 * @note Since @p volume_mesh and @p surface_mesh have different spatial
2915 * dimensions no manifold objects are copied by this function: you must
2916 * attach new manifold objects to @p surface_mesh.
2917 *
2918 *
2919 * @dealiiConceptRequires{
2920 * concepts::is_triangulation_or_dof_handler<MeshType<dim, spacedim>>}
2921 */
2922 template <template <int, int> class MeshType, int dim, int spacedim>
2923 DEAL_II_CXX20_REQUIRES(
2924 (concepts::is_triangulation_or_dof_handler<MeshType<dim, spacedim>>))
2925 #ifdef DOXYGEN
2926 return_type
2927 #else
2928 # ifndef _MSC_VER
2929 std::map<typename MeshType<dim - 1, spacedim>::cell_iterator,
2930 typename MeshType<dim, spacedim>::face_iterator>
2931 # else
2932 typename ExtractBoundaryMesh<MeshType, dim, spacedim>::return_type
2933 # endif
2934 #endif
2935 extract_boundary_mesh(const MeshType<dim, spacedim> &volume_mesh,
2936 MeshType<dim - 1, spacedim> &surface_mesh,
2937 const std::set<types::boundary_id> &boundary_ids =
2938 std::set<types::boundary_id>());
2939
2940 /** @} */
2941
2942
2943 /**
2944 * @name Exceptions
2945 */
2946 /** @{ */
2947
2948
2949 /**
2950 * Exception
2951 */
2952 DeclException0(ExcInvalidRadii);
2953 /**
2954 * Exception
2955 */
2956 DeclException1(ExcInvalidRepetitions,
2957 int,
2958 << "The number of repetitions " << arg1 << " must be >=1.");
2959 /**
2960 * Exception
2961 */
2962 DeclException1(ExcInvalidRepetitionsDimension,
2963 int,
2964 << "The vector of repetitions must have " << arg1
2965 << " elements.");
2966
2967 /**
2968 * Exception for input that is not properly oriented.
2969 */
2970 DeclExceptionMsg(ExcInvalidInputOrientation,
2971 "The input to this function is oriented in a way that will"
2972 " cause all cells to have negative measure.");
2973 /** @} */
2974
2975 #ifndef DOXYGEN
2976 // These functions are only implemented with specializations; declare them
2977 // here
2978 template <>
2979 void
2980 hyper_cube_with_cylindrical_hole(Triangulation<1> &,
2981 const double,
2982 const double,
2983 const double,
2984 const unsigned int,
2985 const bool);
2986
2987 template <>
2988 void
2989 hyper_cube_with_cylindrical_hole(Triangulation<2> &,
2990 const double,
2991 const double,
2992 const double,
2993 const unsigned int,
2994 const bool);
2995
2996 template <>
2997 void
2998 hyper_cube_with_cylindrical_hole(Triangulation<3> &,
2999 const double,
3000 const double,
3001 const double,
3002 const unsigned int,
3003 const bool);
3004
3005 template <>
3006 void
3007 channel_with_cylinder(Triangulation<1> &,
3008 const double,
3009 const unsigned int,
3010 const double,
3011 const bool);
3012
3013 template <>
3014 void
3015 channel_with_cylinder(Triangulation<2> &,
3016 const double,
3017 const unsigned int,
3018 const double,
3019 const bool);
3020
3021 template <>
3022 void
3023 channel_with_cylinder(Triangulation<3> &,
3024 const double,
3025 const unsigned int,
3026 const double,
3027 const bool);
3028
3029
3030
3031 #endif
3032 } // namespace GridGenerator
3033
3034
3035
3036 DEAL_II_NAMESPACE_CLOSE
3037
3038 #endif