Debian Codegraph @

include/deal.II/grid/manifold_lib.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2014 - 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_manifold_lib_h
16 #define dealii_manifold_lib_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/function.h>
22 #include <deal.II/base/function_parser.h>
23
24 #include <deal.II/grid/manifold.h>
25
26 #include <boost/signals2/connection.hpp>
27
28
29 DEAL_II_NAMESPACE_OPEN
30
31 // forward declaration
32 namespace internal
33 {
34 namespace MappingQImplementation
35 {
36 template <int, int>
37 class InverseQuadraticApproximation;
38 }
39 } // namespace internal
40
41
42 /**
43 * Manifold description for a polar coordinate system.
44 *
45 * You can use this Manifold object to describe any sphere, circle,
46 * hypersphere or hyperdisc in two or three dimensions, both as a
47 * co-dimension one manifold descriptor or as co-dimension zero
48 * manifold descriptor, provided that the north and south poles (in
49 * three dimensions) and the center (in both two and three dimensions)
50 * are excluded from the Manifold (as they are singular points of the
51 * polar change of coordinates).
52 *
53 * The two template arguments match the meaning of the two template arguments
54 * in Triangulation<dim, spacedim>; however, this Manifold can be used to
55 * describe both thin and thick objects, and the behavior is identical when
56 * dim <= spacedim, i.e., the functionality of PolarManifold<2,3> is
57 * identical to PolarManifold<3,3>.
58 *
59 * This class works by transforming points from Cartesian coordinates into Polar
60 * coordinates, doing computations (e.g., averages) in that coordinate system,
61 * and then transforming the results back to Cartesian coordinates. For more
62 * information on this approach see the documentation of the base class
63 * (ChartManifold).
64 *
65 * In order for this manifold to work correctly, it cannot be attached to cells
66 * containing the center of the coordinate system or, in 3d, the north and south
67 * poles. Those points are singular points of the coordinate mapping;
68 * consequently, pull_back() is not defined at those points and taking averages
69 * across them does not make sense. We recommend setting the manifold_id of the
70 * cell containing the center to numbers::flat_manifold_id and blending in one
71 * of two ways:
72 *
73 * 1. Only set PolarManifold manifold ids on the curved boundary (i.e., set the
74 * manifold id of faces and not cells). deal.II will use a cell-by-cell
75 * version of transfinite interpolation to compute cell center locations for,
76 * e.g., mesh refinement.
77 * 2. Set the PolarManifold manifold ids on cells and use
78 * TransfiniteInterpolationManifold.
79 *
80 * In 3d, we recommend using SphericalManifold to correctly handle the north and
81 * south poles.
82 *
83 * @ingroup manifold
84 */
85 template <int dim, int spacedim = dim>
86 class PolarManifold : public ChartManifold<dim, spacedim, spacedim>
87 {
88 public:
89 /**
90 * Constructor.
91 *
92 * @param[in] center The center of the coordinate system. Defaults to the
93 * origin.
94 */
95 PolarManifold(const Point<spacedim> center = Point<spacedim>());
96
97 /**
98 * Make a clone of this Manifold object.
99 */
100 virtual std::unique_ptr<Manifold<dim, spacedim>>
101 clone() const override;
102
103 /**
104 * Pull back the given point from the Euclidean space. Will return the polar
105 * coordinates associated with the point @p space_point.
106 */
107 virtual Point<spacedim>
108 pull_back(const Point<spacedim> &space_point) const override;
109
110 /**
111 * Given a point in the spherical coordinate system, this method returns the
112 * Euclidean coordinates associated to the polar coordinates @p chart_point.
113 */
114 virtual Point<spacedim>
115 push_forward(const Point<spacedim> &chart_point) const override;
116
117 /**
118 * Given a point in the spacedim dimensional Euclidean space, this
119 * method returns the derivatives of the function $F$ that maps from
120 * the polar coordinate system to the Euclidean coordinate
121 * system. In other words, it is a matrix of size
122 * $\text{spacedim}\times\text{spacedim}$.
123 *
124 * This function is used in the computations required by the
125 * get_tangent_vector() function.
126 *
127 * Refer to the general documentation of this class for more information.
128 */
129 virtual DerivativeForm<1, spacedim, spacedim>
130 push_forward_gradient(const Point<spacedim> &chart_point) const override;
131
132 /**
133 * @copydoc Manifold::normal_vector()
134 */
135 virtual Tensor<1, spacedim>
136 normal_vector(
137 const typename Triangulation<dim, spacedim>::face_iterator &face,
138 const Point<spacedim> &p) const override;
139
140 /**
141 * Return the center of the spherical coordinate system.
142 */
143 const Point<spacedim> &
144 get_center() const;
145
146 /**
147 * The center of the spherical coordinate system.
148 *
149 * @deprecated Use get_center() instead.
150 */
151 DEAL_II_DEPRECATED_WITH_COMMENT(
152 "Access the center with get_center() instead.")
153 const Point<spacedim> center;
154
155 private:
156 /**
157 * The center of the spherical coordinate system.
158 *
159 * @note This exists to avoid warnings when using center internally.
160 */
161 const Point<spacedim> p_center;
162
163 /**
164 * Helper function which returns the periodicity associated with this
165 * coordinate system, according to dim, chartdim, and spacedim.
166 */
167 static Tensor<1, spacedim>
168 get_periodicity();
169 };
170
171
172
173 /**
174 * Manifold description for a spherical space coordinate system.
175 *
176 * You can use this Manifold object to describe any sphere, circle,
177 * hypersphere or hyperdisc in two or three dimensions. This manifold
178 * can be used as a co-dimension one manifold descriptor of a
179 * spherical surface embedded in a higher dimensional space, or as a
180 * co-dimension zero manifold descriptor for a body with positive
181 * volume, provided that the center of the spherical space is excluded
182 * from the domain. An example for the use of this function would be
183 * in the description of a hyper-shell or hyper-ball geometry, for
184 * example after creating a coarse mesh using GridGenerator::hyper_ball().
185 * (However, it is worth mentioning that generating a good mesh for
186 * a disk or ball is complicated and requires addition steps. See the
187 * "Possibilities for extensions" section of step-6 for an extensive
188 * discussion of how one would construct such meshes and what one
189 * needs to do for it.)
190 *
191 * The two template arguments match the meaning of the two template arguments
192 * in Triangulation<dim, spacedim>, however this Manifold can be used to
193 * describe both thin and thick objects, and the behavior is identical when
194 * dim <= spacedim, i.e., the functionality of SphericalManifold<2,3> is
195 * identical to SphericalManifold<3,3>.
196 *
197 * While PolarManifold reflects the usual notion of polar coordinates,
198 * it may not be suitable for domains that contain either the north or
199 * south poles. Consider for instance the pair of points
200 * $x_1=(1,\pi/3,0)$ and $x_2=(1,\pi/3,\pi)$ in polar
201 * coordinates (lying on the surface of a sphere with radius one, on
202 * a parallel at height $\pi/3$). In this case connecting the points
203 * with a straight line in polar coordinates would take the long road
204 * around the globe, without passing through the north pole.
205 *
206 * These two points would be connected (using a PolarManifold) by the curve
207 * @f{align*}{
208 * s: [0,1] & \rightarrow & \mathbb S^3 \\
209 * t & \mapsto & (1,\pi/3,0) + (0,0,t\pi)
210 * @f}
211 * This curve is not a geodesic on the sphere, and it is not how we
212 * would connect those two points. A better curve, would be the one
213 * passing through the North pole:
214 * @f[
215 * s(t) = x_1 \cos(\alpha(t)) + \kappa \times x_1 \sin(\alpha(t)) +
216 * \kappa ( \kappa \cdot x_1) (1-\cos(\alpha(t))).
217 * @f]
218 * where $\kappa = \frac{x_1 \times x_2}{\Vert x_1 \times x_2 \Vert}$
219 * and $\alpha(t) = t \cdot \arccos(x_1 \cdot x_2)$ for $t\in[0,1]$.
220 * Indeed, this is a geodesic, and it is the natural choice when
221 * connecting points on the surface of the sphere. In the examples above,
222 * the PolarManifold class implements the first way of connecting two
223 * points on the surface of a sphere, while SphericalManifold implements
224 * the second way, i.e., this Manifold connects points using geodesics.
225 * If more than two points are involved through a
226 * SphericalManifold::get_new_points() call, a so-called spherical average is
227 * used where the final point minimizes the weighted distance to all other
228 * points via geodesics.
229 *
230 * In particular, this class implements a Manifold that joins any two
231 * points in space by first projecting them onto the surface of a
232 * sphere with unit radius, then connecting them with a geodesic, and
233 * finally rescaling the final radius so that the resulting one is the
234 * weighted average of the starting radii. This Manifold is identical
235 * to PolarManifold in dimension two, while for dimension three it
236 * returns points that are more uniformly distributed on the sphere,
237 * and it is invariant with respect to rotations of the coordinate
238 * system, therefore avoiding the problems that PolarManifold has at
239 * the poles. Notice, in particular, that computing tangent vectors at
240 * the poles with a PolarManifold is not well defined, while it is
241 * perfectly fine with this class.
242 *
243 * For mathematical reasons, it is impossible to construct a unique
244 * map of a sphere using only geodesic curves, and therefore, using
245 * this class with MappingManifold is discouraged. If you use this
246 * Manifold to describe the geometry of a sphere, you should use
247 * MappingQ as the underlying mapping, and not MappingManifold.
248 *
249 * This Manifold can be used *only* on geometries where a ball with
250 * finite radius is removed from the center. Indeed, the center is a
251 * singular point for this manifold, and if you try to connect two
252 * points across the center, they would travel on spherical
253 * coordinates, avoiding the center.
254 *
255 * The ideal geometry for this Manifold is a hyper shell. If you plan to use
256 * this Manifold on a hyper ball, you have to make sure you do not attach this
257 * Manifold to the cell containing the center. It is advisable to combine this
258 * class with TransfiniteInterpolationManifold to ensure a smooth transition
259 * from a curved shape to the straight coordinate system in the center of the
260 * ball. (See also the extensive discussion in step-65.)
261 *
262 * @ingroup manifold
263 */
264 template <int dim, int spacedim = dim>
265 class SphericalManifold : public Manifold<dim, spacedim>
266 {
267 public:
268 /**
269 * Constructor.
270 *
271 * @param[in] center The center of the coordinate system. Defaults to the
272 * origin.
273 */
274 SphericalManifold(const Point<spacedim> center = Point<spacedim>());
275
276 /**
277 * Make a clone of this Manifold object.
278 */
279 virtual std::unique_ptr<Manifold<dim, spacedim>>
280 clone() const override;
281
282 /**
283 * Given any two points in space, first project them on the surface
284 * of a sphere with unit radius, then connect them with a geodesic
285 * and find the intermediate point, and finally rescale the final
286 * radius so that the resulting one is the convex combination of the
287 * starting radii.
288 */
289 virtual Point<spacedim>
290 get_intermediate_point(const Point<spacedim> &p1,
291 const Point<spacedim> &p2,
292 const double w) const override;
293
294 /**
295 * Compute the derivative of the get_intermediate_point() function
296 * with parameter w equal to zero.
297 */
298 virtual Tensor<1, spacedim>
299 get_tangent_vector(const Point<spacedim> &x1,
300 const Point<spacedim> &x2) const override;
301
302 /**
303 * @copydoc Manifold::normal_vector()
304 */
305 virtual Tensor<1, spacedim>
306 normal_vector(
307 const typename Triangulation<dim, spacedim>::face_iterator &face,
308 const Point<spacedim> &p) const override;
309
310 /**
311 * Compute the normal vectors to the boundary at each vertex.
312 */
313 virtual void
314 get_normals_at_vertices(
315 const typename Triangulation<dim, spacedim>::face_iterator &face,
316 typename Manifold<dim, spacedim>::FaceVertexNormals &face_vertex_normals)
317 const override;
318
319 /**
320 * Compute a new set of points that interpolate between the given points @p
321 * surrounding_points. @p weights is a table with as many columns as @p
322 * surrounding_points.size(). The number of rows in @p weights must match
323 * the length of @p new_points.
324 *
325 * This function is optimized to perform on a collection
326 * of new points, by collecting operations that are not dependent on the
327 * weights outside of the loop over all new points.
328 *
329 * The implementation does not allow for @p surrounding_points and
330 * @p new_points to point to the same array, so make sure to pass different
331 * objects into the function.
332 */
333 virtual void
334 get_new_points(const ArrayView<const Point<spacedim>> &surrounding_points,
335 const Table<2, double> &weights,
336 ArrayView<Point<spacedim>> new_points) const override;
337
338 /**
339 * Return a point on the spherical manifold which is intermediate
340 * with respect to the surrounding points.
341 */
342 virtual Point<spacedim>
343 get_new_point(const ArrayView<const Point<spacedim>> &vertices,
344 const ArrayView<const double> &weights) const override;
345
346 /**
347 * Return the center of the spherical coordinate system.
348 */
349 const Point<spacedim> &
350 get_center() const;
351
352 /**
353 * The center of the spherical coordinate system.
354 *
355 * @deprecated Use get_center() instead.
356 */
357 DEAL_II_DEPRECATED_WITH_COMMENT(
358 "Access the center with get_center() instead.")
359 const Point<spacedim> center;
360
361 private:
362 /**
363 * The center of the spherical coordinate system.
364 *
365 * @note This exists to avoid warnings when using center internally.
366 */
367 const Point<spacedim> p_center;
368
369 /**
370 * Return a point on the spherical manifold which is intermediate
371 * with respect to the surrounding points. This function uses a linear
372 * average of the directions to find an estimated point. It returns a pair
373 * of radius and direction from the center point to the candidate point.
374 */
375 std::pair<double, Tensor<1, spacedim>>
376 guess_new_point(const ArrayView<const Tensor<1, spacedim>> &directions,
377 const ArrayView<const double> &distances,
378 const ArrayView<const double> &weights) const;
379
380 /**
381 * This function provides an internal implementation of the get_new_points()
382 * interface.
383 *
384 * It computes a new set of points that interpolate between the given points
385 * @p
386 * surrounding_points. @p weights is an array view with as many entries as @p
387 * surrounding_points.size() times @p new_points.size().
388 *
389 * This function is optimized to perform on a collection
390 * of new points, by collecting operations that are not dependent on the
391 * weights outside of the loop over all new points.
392 *
393 * The implementation does not allow for @p surrounding_points and
394 * @p new_points to point to the same array, so make sure to pass different
395 * objects into the function.
396 */
397 void
398 do_get_new_points(const ArrayView<const Point<spacedim>> &surrounding_points,
399 const ArrayView<const double> &weights,
400 ArrayView<Point<spacedim>> new_points) const;
401
402 /**
403 * A manifold description to be used for get_new_point in 2d.
404 */
405 const PolarManifold<spacedim> polar_manifold;
406 };
407
408 /**
409 * Cylindrical Manifold description. In three dimensions, points are
410 * transformed using a cylindrical coordinate system along the <tt>x-</tt>,
411 * <tt>y-</tt> or <tt>z</tt>-axis (when using the first constructor of this
412 * class), or an arbitrarily oriented cylinder described by the direction of
413 * its axis and a point located on the axis.
414 *
415 * This class was developed to be used in conjunction with the @p cylinder or
416 * @p cylinder_shell functions of GridGenerator. This function will throw a
417 * run time exception whenever spacedim is not equal to three.
418 *
419 * @ingroup manifold
420 */
421 template <int dim, int spacedim = dim>
422 class CylindricalManifold : public ChartManifold<dim, spacedim, 3>
423 {
424 public:
425 /**
426 * Constructor. Using default values for the constructor arguments yields a
427 * cylinder along the x-axis (<tt>axis=0</tt>). Choose <tt>axis=1</tt> or
428 * <tt>axis=2</tt> for a tube along the y- or z-axis, respectively. The
429 * tolerance value is used to determine if a point is on the axis.
430 */
431 CylindricalManifold(const unsigned int axis = 0,
432 const double tolerance = 1e-10);
433
434 /**
435 * Constructor. If constructed with this constructor, the manifold described
436 * is a cylinder with an axis that points in direction #direction and goes
437 * through the given #point_on_axis. The direction may be arbitrarily
438 * scaled, and the given point may be any point on the axis. The tolerance
439 * value is used to determine if a point is on the axis.
440 */
441 CylindricalManifold(const Tensor<1, spacedim> &direction,
442 const Point<spacedim> &point_on_axis,
443 const double tolerance = 1e-10);
444
445 /**
446 * Make a clone of this Manifold object.
447 */
448 virtual std::unique_ptr<Manifold<dim, spacedim>>
449 clone() const override;
450
451 /**
452 * Compute the cylindrical coordinates $(r, \phi, \lambda)$ for the given
453 * space point where $r$ denotes the distance from the axis,
454 * $\phi$ the angle between the given point and the computed normal
455 * direction, and $\lambda$ the axial position.
456 */
457 virtual Point<3>
458 pull_back(const Point<spacedim> &space_point) const override;
459
460 /**
461 * Compute the Cartesian coordinates for a chart point given in cylindrical
462 * coordinates $(r, \phi, \lambda)$, where $r$ denotes the distance from the
463 * axis, $\phi$ the angle between the given point and the computed normal
464 * direction, and $\lambda$ the axial position.
465 */
466 virtual Point<spacedim>
467 push_forward(const Point<3> &chart_point) const override;
468
469 /**
470 * Compute the derivatives of the mapping from cylindrical coordinates
471 * $(r, \phi, \lambda)$ to cartesian coordinates where $r$ denotes the
472 * distance from the axis, $\phi$ the angle between the given point and the
473 * computed normal direction, and $\lambda$ the axial position.
474 */
475 virtual DerivativeForm<1, 3, spacedim>
476 push_forward_gradient(const Point<3> &chart_point) const override;
477
478 /**
479 * Compute new points on the CylindricalManifold. See the documentation of
480 * the base class for a detailed description of what this function does.
481 */
482 virtual Point<spacedim>
483 get_new_point(const ArrayView<const Point<spacedim>> &surrounding_points,
484 const ArrayView<const double> &weights) const override;
485
486 /**
487 * Get the Tensor parallel to the cylinder's axis.
488 */
489 const Tensor<1, spacedim> &
490 get_direction() const;
491
492 /**
493 * Get a point on the Cylinder's axis.
494 *
495 * @note This argument, like get_direction() and get_tolerance(), just returns
496 * the arguments set in the three-argument constructor.
497 */
498 const Point<spacedim> &
499 get_point_on_axis() const;
500
501 /**
502 * Get the tolerance which determines if a point is on the Cylinder's axis.
503 */
504 double
505 get_tolerance() const;
506
507 private:
508 /**
509 * A vector orthogonal to the normal direction.
510 */
511 const Tensor<1, spacedim> normal_direction;
512
513 /**
514 * The direction vector of the axis.
515 */
516 const Tensor<1, spacedim> direction;
517
518 /**
519 * An arbitrary point on the axis.
520 */
521 const Point<spacedim> point_on_axis;
522
523 /**
524 * Relative tolerance to measure zero distances.
525 */
526 const double tolerance;
527
528 /**
529 * The direction vector perpendicular to both direction and normal_direction.
530 */
531 const Tensor<1, spacedim> dxn;
532 };
533
534 /**
535 * Elliptical manifold description derived from ChartManifold.
536 * More information on the elliptical coordinate system can be found
537 * at <a
538 * href="https://en.wikipedia.org/wiki/Elliptic_coordinate_system">Wikipedia
539 * </a>.
540 *
541 * This is based on the definition of elliptic coordinates $(u,v)$
542 * @f[
543 * \left\lbrace\begin{aligned}
544 * x &= x_0 + c \cosh(u) \cos(v) \\
545 * y &= y_0 + c \sinh(u) \sin(v)
546 * \end{aligned}\right.
547 * @f]
548 * in which $(x_0,y_0)$ are coordinates of the center of the cartesian system.
549 *
550 * The current implementation uses coordinates $(c,v)$, instead of $(u,v)$, and
551 * fixes $u$ according to a given eccentricity. Therefore, this choice
552 * of coordinates generates an elliptical manifold characterized by a constant
553 * eccentricity: $e=\frac{1}{\cosh(u)}$, with $e\in\left]0,1\right[$.
554 *
555 * The constructor of this class will throw an exception if both dim and
556 * spacedim are different from two.
557 *
558 * This manifold can be used to produce hyper_shells with elliptical curvature.
559 * As an example, the test <B>elliptical_manifold_01</B> produces the following
560 * triangulation:
561 * @image html elliptical_hyper_shell.png
562 *
563 * @ingroup manifold
564 */
565 template <int dim, int spacedim = dim>
566 class EllipticalManifold : public ChartManifold<dim, spacedim, spacedim>
567 {
568 public:
569 /**
570 * Constructor that takes the center of the manifold system, the direction of
571 * the major axis, and the manifold eccentricity.
572 * The default major axis is the <tt>x</tt>-axis. The manifold is rotated in
573 * order to align the major axis to the direction specified in input.
574 * @param center Center of the manifold.
575 * @param major_axis_direction Direction of the major axis of the
576 * manifold.
577 * @param eccentricity Eccentricity of the
578 * manifold $e\in\left]0,1\right[$.
579 */
580 EllipticalManifold(const Point<spacedim> &center,
581 const Tensor<1, spacedim> &major_axis_direction,
582 const double eccentricity);
583
584 virtual std::unique_ptr<Manifold<dim, spacedim>>
585 clone() const override;
586
587 /**
588 * @copydoc ChartManifold::pull_back()
589 */
590 virtual Point<spacedim>
591 pull_back(const Point<spacedim> &space_point) const override;
592
593 /**
594 * @copydoc ChartManifold::push_forward()
595 */
596 virtual Point<spacedim>
597 push_forward(const Point<spacedim> &chart_point) const override;
598
599 /**
600 * @copydoc ChartManifold::push_forward_gradient()
601 */
602 virtual DerivativeForm<1, spacedim, spacedim>
603 push_forward_gradient(const Point<spacedim> &chart_point) const override;
604
605 /**
606 * Get the Tensor parallel to the cylinder's major axis.
607 */
608 const Tensor<1, spacedim> &
609 get_major_axis_direction() const;
610
611 /**
612 * Return the center of the elliptical coordinate system.
613 */
614 const Point<spacedim> &
615 get_center() const;
616
617 /**
618 * Return the ellipse's eccentricity.
619 */
620 double
621 get_eccentricity() const;
622
623 private:
624 /**
625 * The direction vector of the major axis.
626 */
627 const Tensor<1, spacedim> direction;
628
629 /**
630 * The center of the manifold.
631 */
632 const Point<spacedim> center;
633
634 /**
635 * The eccentricity.
636 */
637 const double eccentricity;
638
639 /**
640 * Parameters deriving from the eccentricity of the manifold.
641 */
642 const double cosh_u;
643 const double sinh_u;
644
645 /**
646 * @copydoc ChartManifold::get_periodicity()
647 *
648 * For $\text{dim}=2$ and $\text{spacedim}=2$, the first coordinate is
649 * non-periodic, while the second coordinate has a periodicity of $2\pi$.
650 */
651 static Tensor<1, spacedim>
652 get_periodicity();
653 };
654
655
656 /**
657 * Manifold description derived from ChartManifold, based on explicit
658 * Function<spacedim> and Function<chartdim> objects describing the
659 * push_forward() and pull_back() functions.
660 *
661 * You can use this Manifold object to describe any arbitrary shape domain, as
662 * long as you can express it in terms of an invertible map, for which you
663 * provide both the forward expression, and the inverse expression.
664 *
665 * In debug mode, a check is performed to verify that the transformations are
666 * actually one the inverse of the other.
667 *
668 * @ingroup manifold
669 */
670 template <int dim, int spacedim = dim, int chartdim = dim>
671 class FunctionManifold : public ChartManifold<dim, spacedim, chartdim>
672 {
673 public:
674 /**
675 * Explicit functions constructor. Takes a push_forward function of spacedim
676 * components, and a pull_back function of @p chartdim components. See the
677 * documentation of the base class ChartManifold for the meaning of the
678 * optional @p periodicity argument.
679 *
680 * The tolerance argument is used in debug mode to actually check that the
681 * two functions are one the inverse of the other.
682 *
683 * Note: the object constructed in this way stores pointers to the
684 * push_forward and pull_back functions. Therefore, one must guarantee that
685 * the function objects are destroyed only after the constructed manifold.
686 */
687 FunctionManifold(
688 const Function<chartdim> &push_forward_function,
689 const Function<spacedim> &pull_back_function,
690 const Tensor<1, chartdim> &periodicity = Tensor<1, chartdim>(),
691 const double tolerance = 1e-10);
692
693 /**
694 * Same as previous, except this constructor takes ownership of the Function
695 * objects passed as first and second argument, and is ultimately in charge
696 * of deleting the pointers when the FunctionManifold object is destroyed.
697 *
698 * This constructor is useful because it allows creating function objects at
699 * the place of calling the constructor without having to name and later
700 * delete these objects. This allows the following idiom:
701 * FunctionManifold<dim> manifold(std::make_unique<MyPushForward>(...),
702 * std::make_unique<MyPullBack>(...));
703 */
704 FunctionManifold(
705 std::unique_ptr<Function<chartdim>> push_forward,
706 std::unique_ptr<Function<spacedim>> pull_back,
707 const Tensor<1, chartdim> &periodicity = Tensor<1, chartdim>(),
708 const double tolerance = 1e-10);
709
710 /**
711 * Expressions constructor. Takes the expressions of the push_forward
712 * function of spacedim components, and of the pull_back function of @p
713 * chartdim components. See the documentation of the base class
714 * ChartManifold for the meaning of the optional @p periodicity argument.
715 *
716 * The strings should be the readable by the default constructor of the
717 * FunctionParser classes. You can specify custom variable expressions with
718 * the last two optional arguments. If you don't, the default names are
719 * used, i.e., "x,y,z".
720 *
721 * The tolerance argument is used in debug mode to actually check that the
722 * two functions are one the inverse of the other.
723 */
724 FunctionManifold(
725 const std::string push_forward_expression,
726 const std::string pull_back_expression,
727 const Tensor<1, chartdim> &periodicity = Tensor<1, chartdim>(),
728 const typename FunctionParser<spacedim>::ConstMap =
729 typename FunctionParser<spacedim>::ConstMap(),
730 const std::string chart_vars =
731 FunctionParser<chartdim>::default_variable_names(),
732 const std::string space_vars =
733 FunctionParser<spacedim>::default_variable_names(),
734 const double tolerance = 1e-10,
735 const double h = 1e-8);
736
737 /**
738 * If needed, we delete the pointers we own.
739 */
740 virtual ~FunctionManifold() override;
741
742 /**
743 * Make a clone of this Manifold object.
744 */
745 virtual std::unique_ptr<Manifold<dim, spacedim>>
746 clone() const override;
747
748 /**
749 * Given a point in the @p chartdim coordinate system, uses the
750 * push_forward_function to compute the push_forward of points in @p
751 * chartdim space dimensions to @p spacedim space dimensions.
752 */
753 virtual Point<spacedim>
754 push_forward(const Point<chartdim> &chart_point) const override;
755
756 /**
757 * Given a point in the chartdim dimensional Euclidean space, this
758 * method returns the derivatives of the function $F$ that maps from
759 * the sub_manifold coordinate system to the Euclidean coordinate
760 * system. In other words, it is a matrix of size
761 * $\text{spacedim}\times\text{chartdim}$.
762 *
763 * This function is used in the computations required by the
764 * get_tangent_vector() function. The default implementation calls
765 * the get_gradient() method of the
766 * FunctionManifold::push_forward_function() member class. If you
767 * construct this object using the constructor that takes two string
768 * expression, then the default implementation of this method uses a
769 * finite difference scheme to compute the gradients(see the
770 * AutoDerivativeFunction() class for details), and you can specify
771 * the size of the spatial step size at construction time with the
772 * @p h parameter.
773 *
774 * Refer to the general documentation of this class for more information.
775 */
776 virtual DerivativeForm<1, chartdim, spacedim>
777 push_forward_gradient(const Point<chartdim> &chart_point) const override;
778
779 /**
780 * Given a point in the spacedim coordinate system, uses the
781 * pull_back_function to compute the pull_back of points in @p spacedim
782 * space dimensions to @p chartdim space dimensions.
783 */
784 virtual Point<chartdim>
785 pull_back(const Point<spacedim> &space_point) const override;
786
787 private:
788 /**
789 * Constants for the FunctionParser classes.
790 */
791 const typename FunctionParser<spacedim>::ConstMap const_map;
792
793 /**
794 * Pointer to the push_forward function.
795 */
796 ObserverPointer<const Function<chartdim>,
797 FunctionManifold<dim, spacedim, chartdim>>
798 push_forward_function;
799
800 /**
801 * Pointer to the pull_back function.
802 */
803 ObserverPointer<const Function<spacedim>,
804 FunctionManifold<dim, spacedim, chartdim>>
805 pull_back_function;
806
807 /**
808 * Relative tolerance. In debug mode, we check that the two functions
809 * provided at construction time are actually one the inverse of the other.
810 * This value is used as relative tolerance in this check.
811 */
812 const double tolerance;
813
814 /**
815 * Check ownership of the smart pointers. Indicates whether this class is
816 * the owner of the objects pointed to by the previous two member variables.
817 * This value is set in the constructor of the class. If @p true, then the
818 * destructor will delete the function objects pointed to be the two
819 * pointers.
820 */
821 bool owns_pointers;
822
823 /**
824 * The expression used to construct the push_forward function.
825 */
826 const std::string push_forward_expression;
827
828 /**
829 * The expression used to construct the pull_back function.
830 */
831 const std::string pull_back_expression;
832
833 /**
834 * Variable names in the chart domain.
835 */
836 const std::string chart_vars;
837
838 /**
839 * Variable names in the space domain.
840 */
841 const std::string space_vars;
842
843 /**
844 * The finite difference step to use internally.
845 */
846 const double finite_difference_step;
847 };
848
849
850
851 /**
852 * Manifold description for the surface of a Torus in three dimensions. The
853 * Torus is assumed to be in the x-z plane. The reference coordinate system
854 * is given by the angle $phi$ around the y axis, the angle $theta$ around
855 * the centerline of the torus, and the distance to the centerline $w$
856 * (between 0 and 1).
857 *
858 * This class was developed to be used in conjunction with
859 * GridGenerator::torus.
860 *
861 * @ingroup manifold
862 */
863 template <int dim>
864 class TorusManifold : public ChartManifold<dim, 3, 3>
865 {
866 public:
867 static const int chartdim = 3;
868 static const int spacedim = 3;
869
870 /**
871 * Constructor. Specify the radius of the centerline @p centerline_radius and
872 * the radius of the torus' inner circle (@p inner_radius). The variables have
873 * the same meaning as the parameters in GridGenerator::torus().
874 */
875 TorusManifold(const double centerline_radius, const double inner_radius);
876
877 /**
878 * Make a clone of this Manifold object.
879 */
880 virtual std::unique_ptr<Manifold<dim, 3>>
881 clone() const override;
882
883 /**
884 * Pull back operation.
885 */
886 virtual Point<3>
887 pull_back(const Point<3> &p) const override;
888
889 /**
890 * Push forward operation.
891 */
892 virtual Point<3>
893 push_forward(const Point<3> &chart_point) const override;
894
895 /**
896 * Gradient.
897 */
898 virtual DerivativeForm<1, 3, 3>
899 push_forward_gradient(const Point<3> &chart_point) const override;
900
901 /**
902 * Get the radius of the centerline.
903 */
904 double
905 get_centerline_radius() const;
906
907 /**
908 * Get the inner radius of the torus.
909 */
910 double
911 get_inner_radius() const;
912
913 private:
914 double centerline_radius;
915
916 double inner_radius;
917 };
918
919
920
921 /**
922 * A mapping class that extends curved boundary descriptions into the interior
923 * of the computational domain. The outer curved boundary description is
924 * assumed to be given by another manifold (e.g. a polar manifold on a circle).
925 * The mechanism to extend the boundary information is a so-called transfinite
926 * interpolation.
927 * The use of this class is discussed extensively in step-65.
928 *
929 * The formula for extending such a description in 2d is, for example,
930 * described on
931 * <a href="https://en.wikipedia.org/wiki/Transfinite_interpolation">
932 * Wikipedia</a>. Given a point $(u,v)$ on the chart, the image of this point
933 * in real space is given by
934 * @f{align*}{
935 * \mathbf S(u,v) &= (1-v)\mathbf c_0(u)+v \mathbf c_1(u) + (1-u)\mathbf c_2(v)
936 * + u \mathbf c_3(v) \\
937 * &\quad - \left[(1-u)(1-v) \mathbf x_0 + u(1-v) \mathbf x_1 + (1-u)v \mathbf
938 * x_2 + uv \mathbf x_3 \right]
939 * @f}
940 * where $\bf x_0, \bf x_1, \bf x_2, \bf x_3$ denote the four bounding vertices
941 * bounding the image space and $\bf c_0, \bf c_1, \bf c_2, \bf c_3$ are the
942 * four curves describing the lines of the cell. If a curved manifold is
943 * attached to any of these lines, the evaluation is done according to
944 * Manifold::get_new_point() with the two end points of the line and
945 * appropriate weight. In 3d, the generalization of this formula is
946 * implemented, creating a weighted sum of the vertices (positive
947 * contribution), the lines (negative), and the faces (positive contribution).
948 *
949 * This manifold is usually attached to a coarse mesh and then places new
950 * points as a combination of the descriptions on the boundaries, weighted
951 * appropriately according to the position of the point in the original chart
952 * coordinates $(u,v)$. This manifold should be preferred over setting only a
953 * curved manifold on the boundary of a mesh in most situations as it yields
954 * more uniform mesh distributions as the mesh is refined because it switches
955 * from a curved description to a straight description over all children of
956 * the initial coarse cell this manifold was attached to. This way, the curved
957 * nature of the manifold that is originally contained in one <i>coarse</i>
958 * mesh layer will be applied to more than one <i>fine</i> mesh layer once the
959 * mesh gets refined. Note that the mechanisms of
960 * TransfiniteInterpolationManifold are also built into the MappingQ
961 * class when only a surface of a cell is subject to a curved description,
962 * ensuring that even the default case without this manifold gets optimal
963 * convergence rates when applying curved boundary descriptions.
964 *
965 * If no curved boundaries surround a coarse cell, this class reduces to a flat
966 * manifold description.
967 *
968 * To give an example of using this class, the following code attaches a
969 * transfinite manifold to a circle:
970 *
971 * @code
972 * PolarManifold<dim> polar_manifold;
973 * TransfiniteInterpolationManifold<dim> inner_manifold;
974 *
975 * Triangulation<dim> triangulation;
976 * GridGenerator::hyper_ball (triangulation);
977 *
978 * triangulation.set_all_manifold_ids(1);
979 * triangulation.set_all_manifold_ids_on_boundary(0);
980 * triangulation.set_manifold (0, polar_manifold);
981 * inner_manifold.initialize(triangulation);
982 * triangulation.set_manifold (1, inner_manifold);
983 * triangulation.refine_global(4);
984 * @endcode
985 *
986 * In this code, we first set all manifold ids to the id of the transfinite
987 * interpolation, and then re-set the manifold ids on the boundary to identify
988 * the curved boundary described by the polar manifold. With this code, one
989 * gets a really nice mesh:
990 *
991 * <p ALIGN="center">
992 * @image html circular_mesh_transfinite_interpolation.png
993 * </p>
994 *
995 * which is obviously much nicer than the polar manifold applied to just the
996 * boundary:
997 *
998 * <p ALIGN="center">
999 * @image html circular_mesh_only_boundary_manifold.png
1000 * </p>
1001 *
1002 * This manifold is used in a few GridGenerator functions, including
1003 * GridGenerator::channel_with_cylinder.
1004 *
1005 * <h3>Implementation details</h3>
1006 *
1007 * In the implementation of this class, the manifolds surrounding a coarse
1008 * cell are queried repeatedly to compute points on their interior. For
1009 * optimal mesh quality, those manifolds should be compatible with a chart
1010 * notion. For example, computing a point that is 0.25 along the line between
1011 * two vertices using the weights 0.25 and 0.75 for the two vertices should
1012 * give the same result as first computing the mid point at 0.5 and then again
1013 * compute the midpoint between the first vertex and coarse mid point. This is
1014 * the case for most of the manifold classes provided by deal.II, such as
1015 * SphericalManifold or PolarManifold, but it might be violated by naive
1016 * implementations. In case the quality of the manifold is not good enough,
1017 * upon mesh refinement it may happen that the transformation to a chart
1018 * inside the get_new_point() or get_new_points() methods produces points that
1019 * are outside the unit cell. Then this class throws an exception of type
1020 * Mapping::ExcTransformationFailed. In that case, the mesh should be refined
1021 * before attaching this class, as done in the following example:
1022 *
1023 * @code
1024 * SphericalManifold<dim> spherical_manifold;
1025 * TransfiniteInterpolationManifold<dim> inner_manifold;
1026 * Triangulation<dim> triangulation;
1027 * GridGenerator::hyper_ball (triangulation);
1028 *
1029 * triangulation.set_all_manifold_ids(1);
1030 * triangulation.set_all_manifold_ids_on_boundary(0);
1031 * triangulation.set_manifold (0, spherical_manifold);
1032 * inner_manifold.initialize(triangulation);
1033 * triangulation.set_manifold (1, inner_manifold);
1034 * triangulation.refine_global(1);
1035 *
1036 * // initialize the transfinite manifold again
1037 * inner_manifold.initialize(triangulation);
1038 * triangulation.refine_global(4);
1039 * @endcode
1040 *
1041 * @note For performance and accuracy reasons, it is recommended to apply the
1042 * transfinite manifold to as coarse a mesh as possible. Regarding accuracy,
1043 * the curved description can only be applied to new points created from a
1044 * given neighborhood, and the grid quality is typically higher when extending
1045 * the curved description over as large a domain as possible. Regarding
1046 * performance, the identification of the correct coarse cell in the
1047 * get_new_point() method needs to pass all coarse cells, so expect a linear
1048 * complexity in the number of coarse cells for each single mapping operation,
1049 * i.e., at least quadratic in the number of coarse mesh cells for any global
1050 * operation on the whole mesh. Thus, the current implementation is only
1051 * economical when there are not more than a few hundreds of coarse cells. To
1052 * make performance better for larger numbers of cells, one could extend the
1053 * current implementation by a pre-identification of relevant cells with
1054 * axis-aligned bounding boxes.
1055 *
1056 * @ingroup manifold
1057 */
1058 template <int dim, int spacedim = dim>
1059 class TransfiniteInterpolationManifold : public Manifold<dim, spacedim>
1060 {
1061 public:
1062 /**
1063 * Constructor.
1064 */
1065 TransfiniteInterpolationManifold();
1066
1067 /**
1068 * Destructor.
1069 */
1070 virtual ~TransfiniteInterpolationManifold() override;
1071
1072 /**
1073 * Make a clone of this Manifold object.
1074 */
1075 virtual std::unique_ptr<Manifold<dim, spacedim>>
1076 clone() const override;
1077
1078 /**
1079 * Initializes the manifold with a coarse mesh. The prerequisite for using
1080 * this class is that the input triangulation is uniformly refined and the
1081 * manifold is later attached to the same triangulation.
1082 *
1083 * Whenever the assignment of manifold ids changes on the level of the
1084 * triangulation which this class was initialized with, initialize() must be
1085 * called again to update the manifold ids connected to the coarse cells.
1086 *
1087 * @note The triangulation used to construct the manifold must not be
1088 * destroyed during the usage of this object.
1089 */
1090 void
1091 initialize(const Triangulation<dim, spacedim> &triangulation);
1092
1093 /**
1094 * Return the point which shall become the new vertex surrounded by the
1095 * given points @p surrounding_points. @p weights contains appropriate
1096 * weights for the surrounding points according to which the manifold
1097 * determines the new point's position.
1098 *
1099 * The implementation in this class overrides the method in the base class
1100 * and computes the new point by a transfinite interpolation. The first step
1101 * in the implementation is to identify the coarse cell on which the
1102 * surrounding points are located. Then, the coordinates are transformed to
1103 * the unit coordinates on the coarse cell by a Newton iteration, where the
1104 * new point is then computed according to the weights. Finally, it is
1105 * pushed forward to the real space according to the transfinite
1106 * interpolation.
1107 */
1108 virtual Point<spacedim>
1109 get_new_point(const ArrayView<const Point<spacedim>> &surrounding_points,
1110 const ArrayView<const double> &weights) const override;
1111
1112 /**
1113 * Compute a new set of points that interpolate between the given points @p
1114 * surrounding_points. @p weights is a table with as many columns as @p
1115 * surrounding_points.size(). The number of columns in @p weights must match
1116 * the length of @p new_points.
1117 *
1118 * The implementation in this class overrides the method in the base class
1119 * and computes the new point by a transfinite interpolation. The first step
1120 * in the implementation is to identify the coarse cell on which the
1121 * surrounding points are located. Then, the coordinates are transformed to
1122 * the unit coordinates on the coarse cell by a Newton iteration, where the
1123 * new points are then computed according to the weights. Finally, the is
1124 * pushed forward to the real space according to the transfinite
1125 * interpolation.
1126 *
1127 * The implementation does not allow for @p surrounding_points and
1128 * @p new_points to point to the same vector, so make sure to pass different
1129 * objects into the function.
1130 */
1131 virtual void
1132 get_new_points(const ArrayView<const Point<spacedim>> &surrounding_points,
1133 const Table<2, double> &weights,
1134 ArrayView<Point<spacedim>> new_points) const override;
1135
1136 private:
1137 /**
1138 * Internal function to identify the most suitable cells (=charts) where the
1139 * given surrounding points are located. We use a cheap algorithm to
1140 * identify the cells and rank the cells by probability before we actually
1141 * do the search inside the relevant cells. The cells are sorted by the
1142 * distance of a Q1 approximation of the inverse mapping to the unit cell of
1143 * the surrounding points. We expect at most 20 cells (it should be up to 8
1144 * candidates on a 3d structured mesh and a bit more on unstructured ones,
1145 * typically we only get two or three), so get an array with 20 entries of a
1146 * the indices <tt>cell->index()</tt>.
1147 */
1148 std::array<unsigned int, 20>
1149 get_possible_cells_around_points(
1150 const ArrayView<const Point<spacedim>> &surrounding_points) const;
1151
1152 /**
1153 * Finalizes the identification of the correct chart and populates @p
1154 * chart_points with the pullbacks of the surrounding points. This method
1155 * internally calls @p get_possible_cells_around_points().
1156 *
1157 * Return an iterator to the cell on which the chart is defined.
1158 */
1159 typename Triangulation<dim, spacedim>::cell_iterator
1160 compute_chart_points(
1161 const ArrayView<const Point<spacedim>> &surrounding_points,
1162 ArrayView<Point<dim>> chart_points) const;
1163
1164 /**
1165 * Pull back operation into the unit coordinates on the given coarse cell.
1166 *
1167 * This method is currently based on a Newton-like iteration to find the
1168 * point in the origin. One may speed up the iteration by providing a good
1169 * initial guess as the third argument. If no better point is known, use
1170 * cell->real_to_unit_cell_affine_approximation(p)
1171 *
1172 * @note This internal function is currently not compatible with the
1173 * ChartManifold::pull_back() function because the given class represents an
1174 * atlas of charts, not a single chart. Thus, the pull_back() operation is
1175 * only valid with the additional information of the chart, given by a cell
1176 * on the coarse grid. An alternative implementation could shift the index
1177 * depending on the coarse cell for a 1-to-1 relation between the chart space
1178 * and the image space.
1179 */
1180 Point<dim>
1181 pull_back(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1182 const Point<spacedim> &p,
1183 const Point<dim> &initial_guess) const;
1184
1185 /**
1186 * Push forward operation.
1187 *
1188 * @note This internal function is currently not compatible with the
1189 * ChartManifold::push_forward() function because the given class represents
1190 * an atlas of charts, not a single chart. Thus, the push_forward()
1191 * operation is only valid with the additional information of the chart,
1192 * given by a cell on the coarse grid. An alternative implementation could
1193 * shift the index depending on the coarse cell for a 1-to-1 relation
1194 * between the chart space and the image space.
1195 */
1196 Point<spacedim>
1197 push_forward(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1198 const Point<dim> &chart_point) const;
1199
1200 /**
1201 * Gradient of the push_forward method.
1202 *
1203 * @note This internal function is not compatible with the
1204 * ChartManifold::push_forward_gradient() function because the given class
1205 * represents an atlas of charts, not a single chart. Furthermore, this
1206 * private function also requires the user to provide the result of the
1207 * push_forward() call on the chart point for the single use case of this
1208 * function, namely inside a Newton iteration where the gradient is computed
1209 * by finite differences.
1210 */
1211 DerivativeForm<1, dim, spacedim>
1212 push_forward_gradient(
1213 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1214 const Point<dim> &chart_point,
1215 const Point<spacedim> &pushed_forward_chart_point) const;
1216
1217 /**
1218 * The underlying triangulation.
1219 */
1220 const Triangulation<dim, spacedim> *triangulation;
1221
1222 /**
1223 * The level of the mesh cells where the transfinite approximation is
1224 * applied, usually level 0.
1225 */
1226 int level_coarse;
1227
1228 /**
1229 * In case there all surrounding manifolds are the transfinite manifold or
1230 * have default (invalid) manifold id, the manifold degenerates to a flat
1231 * manifold and we can choose cheaper algorithms for the push_forward method.
1232 */
1233 std::vector<bool> coarse_cell_is_flat;
1234
1235 /**
1236 * A flat manifold used to compute new points in the chart space where we
1237 * use a FlatManifold description.
1238 */
1239 FlatManifold<dim> chart_manifold;
1240
1241 /**
1242 * A vector of quadratic approximations to the inverse map from real points
1243 * to chart points for each of the coarse mesh cells.
1244 */
1245 std::vector<internal::MappingQImplementation::
1246 InverseQuadraticApproximation<dim, spacedim>>
1247 quadratic_approximation;
1248
1249 /**
1250 * The connection to Triangulation::signals::clear that must be reset once
1251 * this class goes out of scope.
1252 */
1253 boost::signals2::connection clear_signal;
1254 };
1255
1256 /*----------------------------- inline functions -----------------------------*/
1257
1258 template <int dim, int spacedim>
1259 inline const Point<spacedim> &
1260 PolarManifold<dim, spacedim>::get_center() const
1261 {
1262 return p_center;
1263 }
1264
1265
1266
1267 template <int dim, int spacedim>
1268 inline const Point<spacedim> &
1269 SphericalManifold<dim, spacedim>::get_center() const
1270 {
1271 return p_center;
1272 }
1273
1274
1275
1276 template <int dim, int spacedim>
1277 inline const Tensor<1, spacedim> &
1278 CylindricalManifold<dim, spacedim>::get_direction() const
1279 {
1280 return direction;
1281 }
1282
1283
1284
1285 template <int dim, int spacedim>
1286 inline const Point<spacedim> &
1287 CylindricalManifold<dim, spacedim>::get_point_on_axis() const
1288 {
1289 return point_on_axis;
1290 }
1291
1292
1293
1294 template <int dim, int spacedim>
1295 inline double
1296 CylindricalManifold<dim, spacedim>::get_tolerance() const
1297 {
1298 return tolerance;
1299 }
1300
1301
1302
1303 template <int dim, int spacedim>
1304 inline const Tensor<1, spacedim> &
1305 EllipticalManifold<dim, spacedim>::get_major_axis_direction() const
1306 {
1307 return direction;
1308 }
1309
1310
1311
1312 template <int dim, int spacedim>
1313 inline const Point<spacedim> &
1314 EllipticalManifold<dim, spacedim>::get_center() const
1315 {
1316 return center;
1317 }
1318
1319
1320
1321 template <int dim, int spacedim>
1322 inline double
1323 EllipticalManifold<dim, spacedim>::get_eccentricity() const
1324 {
1325 return eccentricity;
1326 }
1327
1328
1329
1330 template <int dim>
1331 inline double
1332 TorusManifold<dim>::get_centerline_radius() const
1333 {
1334 return centerline_radius;
1335 }
1336
1337
1338
1339 template <int dim>
1340 inline double
1341 TorusManifold<dim>::get_inner_radius() const
1342 {
1343 return inner_radius;
1344 }
1345
1346 DEAL_II_NAMESPACE_CLOSE
1347
1348 #endif