Debian Codegraph @

include/deal.II/grid/manifold.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2014 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_tria_manifold_h
16 #define dealii_tria_manifold_h
17
18
19 /*---------------------------- manifold.h ---------------------------*/
20
21 #include <deal.II/base/config.h>
22
23 #include <deal.II/base/array_view.h>
24 #include <deal.II/base/derivative_form.h>
25 #include <deal.II/base/enable_observer_pointer.h>
26 #include <deal.II/base/point.h>
27 #include <deal.II/base/quadrature_lib.h>
28
29 #include <deal.II/grid/tria.h>
30
31 DEAL_II_NAMESPACE_OPEN
32
33 // forward declaration
34 #ifndef DOXYGEN
35 template <int, typename>
36 class Table;
37 #endif
38
39 /**
40 * We collect here some helper functions used in the Manifold<dim,spacedim>
41 * classes.
42 */
43 namespace Manifolds
44 {
45 /**
46 * A <code>constexpr</code> helper function that returns the number of
47 * default points for the structure type pointed to by the given
48 * <code>MeshIteratorType</code>. See the documentation of
49 * Manifolds::get_default_points_and_weights() for more information.
50 */
51 template <typename MeshIteratorType>
52 inline constexpr std::size_t
53 n_default_points_per_cell()
54 {
55 // Note that in C++11 a constexpr function can only have a return
56 // statement, so we cannot alias the structure dimension
57 return GeometryInfo<MeshIteratorType::AccessorType::structure_dimension>::
58 vertices_per_cell +
59 GeometryInfo<MeshIteratorType::AccessorType::structure_dimension>::
60 lines_per_cell +
61 GeometryInfo<MeshIteratorType::AccessorType::structure_dimension>::
62 quads_per_cell +
63 GeometryInfo<MeshIteratorType::AccessorType::structure_dimension>::
64 hexes_per_cell -
65 1; // don't count the cell itself, just the bounding objects
66 }
67
68 /**
69 * Given a general mesh iterator, construct arrays of quadrature points and
70 * weights that contain the following points:
71 * - If the iterator points to a line, then the quadrature points
72 * are the two vertices of the line. This results in a point vector
73 * with two points.
74 * - If the iterator points to a quad, then the quadrature points
75 * are the vertices and line mid-points. This results in a point vector
76 * with eight (4+4) points.
77 * - If the iterator points to a hex, then the quadrature points
78 * are the vertices, the line mid-points, and the face mid-points.
79 * This results in a points vector with 26 (8+12+6) points.
80 *
81 * The quadrature weights for these points are either chosen identically and
82 * equal to one over the number of quadrature points (if @p
83 * with_interpolation is @p false), or in a way that gives points closer to
84 * the cell center (measured on the reference cell) a higher weight. These
85 * weights correspond to the weights applied to lines and vertices in
86 * transfinite interpolation (see TransfiniteInterpolationManifold for a
87 * more thorough description) if @p with_interpolation is @p true.
88 *
89 * The function is primarily used to construct the input argument
90 * for the Manifold::get_new_point() function, which computes a new
91 * point on a manifold based on a weighted average of "surrounding"
92 * points represented by the quadrature points and weights stored in the
93 * returned pair of vectors. This function creates such an object based on
94 * the points that "surround" a cell, face, or edge, and weights
95 * are chosen in a way appropriate for computing the new "mid-point"
96 * of the object pointed to. An example of where this is necessary
97 * is for mesh refinement, where (using the 2d situation as an example)
98 * we need to first create new edge mid-points, and then a new cell-point.
99 *
100 * @param[in] iterator A mesh iterator that points to either a line, quad,
101 * or hex.
102 * @param[in] with_interpolation Whether or not to compute the quadrature
103 * weights from transfinite interpolation, as discussed above.
104 * @tparam MeshIteratorType An iterator type that corresponds to either
105 * Triangulation::cell_iterator (or variants such as
106 * Triangulation::active_cell_iterator or DoFHandler::cell_iterator) or
107 * that is the result of statements such as
108 * <code>cell-@>face(f)</code> or <code>cell-@>line(l)</code>.
109 */
110 template <typename MeshIteratorType>
111 std::pair<std::array<Point<MeshIteratorType::AccessorType::space_dimension>,
112 n_default_points_per_cell<MeshIteratorType>()>,
113 std::array<double, n_default_points_per_cell<MeshIteratorType>()>>
114 get_default_points_and_weights(const MeshIteratorType &iterator,
115 const bool with_interpolation = false);
116 } // namespace Manifolds
117
118
119
120 /**
121 * Manifolds are used to describe the geometry of boundaries of domains as
122 * well as the geometry of the interior. Manifold objects are therefore
123 * associated with cells, faces, and/or edges, either by direct user action
124 * or, if a user program does not do this explicitly, a default manifold
125 * object is used.
126 *
127 * Manifolds are best understood by using the language of differential
128 * geometry, but their common uses can be easily described simply through
129 * examples. An exhaustive discussion of how, where, and why this class
130 * is used is provided in the
131 * @ref geometry_paper "geometry paper".
132 *
133 *
134 * <h3>Common use case: Creating a new vertex</h3>
135 *
136 * In the most essential use of manifolds, manifold descriptions are used
137 * to create a "point between other points". For example, when a triangulation
138 * creates a new vertex on a cell, face, or edge, it determines the new
139 * vertex' coordinates through the following function call:
140 * @code
141 * ...
142 * Point<spacedim> new_vertex = manifold.get_new_point (points,weights);
143 * ...
144 * @endcode
145 * Here, @p points is a collection of points in @p spacedim dimension,
146 * and @p a collection of corresponding weights. The points
147 * in this context will then be the vertices of the cell, face, or edge, and
148 * the weights are typically one over the number of points when a new midpoint
149 * of the cell, face, or edge is needed. Derived classes then will implement the
150 * Manifold::get_new_point() function in a way that computes the location of
151 * this new point. In the simplest case, for example in the FlatManifold class,
152 * the function simply computes the arithmetic average (with given weights) of
153 * the given points. However, other classes do something differently; for
154 * example, the SphericalManifold class, which is used to describe domains that
155 * form (part of) the sphere, will ensure that, given the two vertices of an
156 * edge at the boundary, the new returned point will lie on the grand circle
157 * that connects the two points, rather than choosing a point that is half-way
158 * between the two points in ${\mathbb R}^d$.
159 *
160 *
161 * @note Unlike almost all other cases in the library, we here interpret the points
162 * to be in real space, not on the reference cell.
163 *
164 * Manifold::get_new_point() has a default implementation that can
165 * simplify this process somewhat: Internally, the function calls the
166 * Manifold::get_intermediate_point() to compute pair-wise
167 * intermediate points. Internally the
168 * Manifold::get_intermediate_point() calls the
169 * Manifold::project_to_manifold() function after computing the convex
170 * combination of the given points. This allows derived classes to
171 * only overload Manifold::project_to_manifold() for simple
172 * situations. This is often useful when describing manifolds that are
173 * embedded in higher dimensional space, e.g., the surface of a
174 * sphere. In those cases, the desired new point may be computed
175 * simply by the (weighted) average of the provided points, projected
176 * back out onto the sphere.
177 *
178 *
179 * <h3>Common use case: Computing tangent vectors</h3>
180 *
181 * The second use of this class is in computing directions on domains and
182 * boundaries. For example, we may need to compute the normal vector to a
183 * face in order to impose the no-flow boundary condition
184 * $\mathbf u \cdot \mathbf n = 0$ (see the
185 * VectorTools::compute_no_normal_flux_constraints() as an example). Similarly,
186 * we may need normal vectors in the computation of the normal component of
187 * the gradient of the numerical solution in order to compute the jump in the
188 * gradient of the solution in error estimators (see, for example, the
189 * KellyErrorEstimator class).
190 *
191 * To make this possible, the Manifold class provides a member function
192 * (to be implemented by derived classes) that computes a "vector tangent
193 * to the manifold at one point, in direction of another point" via the
194 * Manifold::get_tangent_vector() function. For example, in 2d, one would
195 * use this function with the two vertices of an edge at the boundary
196 * to compute a "tangential" vector along the edge, and then get the normal
197 * vector by rotation by 90 degrees. In 3d, one would compute the two
198 * vectors "tangential" to the two edges of a boundary face adjacent to a
199 * boundary vertex, and then take the cross product of these two to
200 * obtain a vector normal to the boundary.
201 *
202 * For reasons that are more
203 * difficult to understand, these direction vectors are normalized in a very
204 * specific way, rather than to have unit norm. See the documentation of
205 * Manifold::get_tangent_vector(), as well as below, for more information.
206 *
207 * In the simplest case (namely, the FlatManifold class), these tangent
208 * vectors are just the difference vector between the two given points.
209 * However, in more complicated (and more interesting) cases, the direction may
210 * be different. For example, for the SphericalManifold case, if the two given
211 * points lie on a common grand circle around the origin, then the tangent
212 * vector will be tangential to the grand circle, rather than pointing straight
213 * from one point to the other.
214 *
215 *
216 * <h3>A unified description</h3>
217 *
218 * The "real" way to understand what this class does is to see it in the
219 * framework of differential geometry. More specifically, differential geometry
220 * is fundamentally based on the assumption that two sufficiently close points
221 * are connected via a line of "shortest distance". This line is called a
222 * "geodesic", and it is selected from all other lines that connect the two
223 * points by the property that it is shortest if distances are measured in
224 * terms of the "metric" that describes a manifold. To give examples, recall
225 * that the geodesics of a flat manifold (implemented in the FlatManifold
226 * class) are simply the straight lines connecting two points, whereas for
227 * spherical manifolds (see the SphericalManifold class) geodesics between
228 * two points of same distance are the grand circles, and are in general
229 * curved lines when connecting two lines of different distance from the
230 * origin.
231 *
232 * In the following discussion, and for the purposes of implementing the
233 * current class, the concept of "metrics" that is so fundamental to
234 * differential geometry is no longer of great importance to us. Rather,
235 * everything can simply be described by postulating the existence of
236 * geodesics connecting points on a manifold.
237 *
238 * Given geodesics, the operations discussed in the previous two sections
239 * can be described in a more formal way. In essence, they rely on the
240 * fact that we can assume that a geodesic is parameterized by a "time"
241 * like variable $t$ so that $\mathbf s(t)$ describes the curve and so
242 * that $\mathbf s(0)$ is the location of the first and $\mathbf s(1)$
243 * the location of the second point. Furthermore, $\mathbf s(t)$ traces
244 * out the geodesic at constant speed, covering equal distance in equal
245 * time (as measured by the metric). Note that this parameterization
246 * uses time, not arc length to denote progress along the geodesic.
247 *
248 * In this picture, computing a mid-point between points $\mathbf x_1$
249 * and $\mathbf x_2$, with weights $w_1$ and $w_2=1-w_1$, simply
250 * requires computing the point $\mathbf s(w_1)$. Computing a new
251 * point as a weighted average of more than two points can be done
252 * by considering pairwise geodesics, finding suitable points on
253 * the geodetic between the first two points, then on the geodetic
254 * between this new point and the third given point, etc.
255 *
256 * Likewise, the "tangential" vector described above is simply the
257 * velocity vector, $\mathbf s'(t)$, evaluated at one of the end
258 * points of a geodesic (i.e., at $t=0$ or $t=1$). In the case of a flat
259 * manifold, the geodesic is simply the straight line connecting two points,
260 * and the velocity vector is just the connecting vector in that
261 * case. On the other hand, for two points on a spherical manifold,
262 * the geodesic is a grand circle, and the velocity vector is
263 * tangent to the spherical surface.
264 *
265 * Note that if we wanted to, we could use this to compute the length
266 * of the geodesic that connects two points $\mathbf x_1$
267 * and $\mathbf x_2$ by computing $\int_0^1 \|\mathbf s'(t)\| dt$
268 * along the geodesic that connects them, but this operation will
269 * not be of use to us in practice. One could also conceive
270 * computing the direction vector using the "new point" operation
271 * above, using the formula $\mathbf s'(0)=\lim_{w\rightarrow 0}
272 * \frac{\mathbf s(w)-\mathbf s(0)}{w}$ where all we need to do
273 * is compute the new point $\mathbf s(w)$ with weights $w$ and
274 * $1-w$ along the geodesic connecting $\mathbf x_1$ and $\mathbf x_2$.
275 * The default implementation of the function does this, by evaluating
276 * the quotient for a small but finite weight $w$.
277 * In practice, however, it is almost always possible to explicitly
278 * compute the direction vector, i.e., without the need to numerically
279 * approximate the limit process, and derived classes should do so.
280 *
281 *
282 * @ingroup manifold
283 */
284 template <int dim, int spacedim = dim>
285 class Manifold : public EnableObserverPointer
286 {
287 public:
288 // explicitly check for sensible template arguments
289 static_assert(dim <= spacedim,
290 "The dimension <dim> of a Manifold must be less than or "
291 "equal to the space dimension <spacedim> in which it lives.");
292
293
294 /**
295 * Type keeping information about the normals at the vertices of a face of a
296 * cell. Thus, there are <tt>GeometryInfo<dim>::vertices_per_face</tt>
297 * normal vectors, that define the tangent spaces of the boundary at the
298 * vertices. Note that the vectors stored in this object are not required to
299 * be normalized, nor to actually point outward, as one often will only want
300 * to check for orthogonality to define the tangent plane; if a function
301 * requires the normals to be normalized, then it must do so itself.
302 *
303 * For obvious reasons, this type is not useful in 1d.
304 */
305 using FaceVertexNormals =
306 std::array<Tensor<1, spacedim>, GeometryInfo<dim>::vertices_per_face>;
307
308
309 /**
310 * Destructor. Does nothing here, but needs to be declared virtual to make
311 * class hierarchies derived from this class possible.
312 */
313 virtual ~Manifold() override = default;
314
315 /**
316 * Return a copy of this manifold.
317 *
318 * Every derived class should implement this operation in a sensible manner.
319 */
320 virtual std::unique_ptr<Manifold<dim, spacedim>>
321 clone() const = 0;
322
323 /**
324 * @name Computing the location of points.
325 */
326 /// @{
327
328 /**
329 * Return an intermediate point between two given
330 * points. Overloading this function allows the default pair-wise
331 * reduction implementation of the method get_new_point() that takes
332 * a Quadrature object as input to work properly.
333 *
334 * An implementation of this function should returns a parametric
335 * curve on the manifold, joining the points `p1` and `p2`, with
336 * parameter `w` in the interval [0,1]. In particular
337 * `get_intermediate_point(p1, p2, 0.0)` should return `p1` and
338 * `get_intermediate_point(p1, p2, 1.0)` should return `p2`.
339 *
340 * In its default implementation, this function calls the
341 * project_to_manifold() method with the convex combination of `p1`
342 * and `p2`. User classes can get away by simply implementing the
343 * project_to_manifold() method.
344 */
345 virtual Point<spacedim>
346 get_intermediate_point(const Point<spacedim> &p1,
347 const Point<spacedim> &p2,
348 const double w) const;
349
350 /**
351 * Return the point which shall become the new vertex surrounded by the
352 * given points @p surrounding_points. @p weights contains appropriate
353 * weights for the surrounding points according to which the manifold
354 * determines the new point's position.
355 *
356 * In its default implementation it uses a pair-wise reduction of
357 * the points by calling the function get_intermediate_point() on the first
358 * two points, then on the resulting point and the next, until all points in
359 * the vector have been taken into account. User classes can get away by
360 * simply implementing the get_intermediate_point() function. Notice that
361 * by default the get_intermediate_point() function calls the
362 * project_to_manifold() function with the convex combination of its
363 * arguments. For simple situations you may get away by implementing
364 * only the project_to_manifold() function.
365 */
366 virtual Point<spacedim>
367 get_new_point(const ArrayView<const Point<spacedim>> &surrounding_points,
368 const ArrayView<const double> &weights) const;
369
370
371 /**
372 * Compute a new set of points that interpolate between the given points @p
373 * surrounding_points. @p weights is a table with as many columns as @p
374 * surrounding_points.size(). The number of rows in @p weights must match
375 * the length of @p new_points.
376 *
377 * In its default implementation, this function simply calls get_new_point()
378 * on each row of @p weights and writes those points into the output array
379 * @p new_points. However, this function is more efficient if multiple new
380 * points need to be generated like in MappingQ and the manifold does
381 * expensive transformations between a chart space and the physical space,
382 * such as ChartManifold. For this function, the surrounding points need to
383 * be transformed back to the chart sparse only once, rather than for every
384 * call to get_new_point(). If efficiency is not important, you may get away
385 * by implementing only the get_new_point() function.
386 *
387 * The implementation does not allow for @p surrounding_points and
388 * @p new_points to point to the same array, so make sure to pass different
389 * objects into the function.
390 */
391 virtual void
392 get_new_points(const ArrayView<const Point<spacedim>> &surrounding_points,
393 const Table<2, double> &weights,
394 ArrayView<Point<spacedim>> new_points) const;
395
396 /**
397 * Given a point which lies close to the given manifold, it modifies it and
398 * projects it to manifold itself.
399 *
400 * This class is used by the default implementation of the function
401 * get_new_point() and should be implemented by derived classes. The default
402 * implementation simply throws an exception if called.
403 *
404 * If your manifold is simple, you could implement this function only, and
405 * the default behavior should work out of the box.
406 */
407 virtual Point<spacedim>
408 project_to_manifold(
409 const ArrayView<const Point<spacedim>> &surrounding_points,
410 const Point<spacedim> &candidate) const;
411
412 /**
413 * Backward compatibility interface. Return the point which shall become
414 * the new middle vertex of the two children of a regular line. In 2d, this
415 * line is a line at the boundary, while in 3d, it is bounding a face at the
416 * boundary (the lines therefore is also on the boundary).
417 *
418 * The default implementation of this function passes its argument to the
419 * Manifolds::get_default_points_and_weights() function, and then calls the
420 * Manifold<dim,spacedim>::get_new_point() function. User derived classes
421 * can overload Manifold<dim,spacedim>::get_new_point() or
422 * Manifold<dim,spacedim>::project_to_manifold(), which is called by the
423 * default implementation of Manifold<dim,spacedim>::get_new_point().
424 */
425 virtual Point<spacedim>
426 get_new_point_on_line(
427 const typename Triangulation<dim, spacedim>::line_iterator &line) const;
428
429 /**
430 * Backward compatibility interface. Return the point which shall become the
431 * common point of the four children of a quad at the boundary in three or
432 * more spatial dimensions. This function therefore is only useful in at
433 * least three dimensions and should not be called for lower dimensions.
434 *
435 * This function is called after the four lines bounding the given @p quad
436 * are refined, so you may want to use the information provided by
437 * <tt>quad->line(i)->child(j)</tt>, <tt>i=0...3</tt>, <tt>j=0,1</tt>.
438 *
439 * The default implementation of this function passes its argument to the
440 * Manifolds::get_default_points_and_weights() function, and then calls the
441 * Manifold<dim,spacedim>::get_new_point() function. User derived classes
442 * can overload Manifold<dim,spacedim>::get_new_point() or
443 * Manifold<dim,spacedim>::project_to_manifold(), which is called by the
444 * default implementation of Manifold<dim,spacedim>::get_new_point().
445 */
446 virtual Point<spacedim>
447 get_new_point_on_quad(
448 const typename Triangulation<dim, spacedim>::quad_iterator &quad) const;
449
450 /**
451 * Backward compatibility interface. Return the point which shall become
452 * the common point of the eight children of a hex in three or spatial
453 * dimensions. This function therefore is only useful in at least three
454 * dimensions and should not be called for lower dimensions.
455 *
456 * This function is called after the all the bounding objects of the given
457 * @p hex are refined, so you may want to use the information provided by
458 * <tt>hex->quad(i)->line(j)->child(k)</tt>, <tt>i=0...5</tt>,
459 * <tt>j=0...3</tt>, <tt>k=0,1</tt>.
460 *
461 * The default implementation of this function passes its argument to the
462 * Manifolds::get_default_points_and_weights() function, and then calls the
463 * Manifold<dim,spacedim>::get_new_point() function. User derived classes
464 * can overload Manifold<dim,spacedim>::get_new_point() or
465 * Manifold<dim,spacedim>::project_to_manifold(), which is called by the
466 * default implementation of Manifold<dim,spacedim>::get_new_point().
467 */
468 virtual Point<spacedim>
469 get_new_point_on_hex(
470 const typename Triangulation<dim, spacedim>::hex_iterator &hex) const;
471
472
473 /**
474 * Backward compatibility interface. Depending on <tt>dim=2</tt> or
475 * <tt>dim=3</tt> this function calls the get_new_point_on_line or the
476 * get_new_point_on_quad function. It throws an exception for
477 * <tt>dim=1</tt>. This wrapper allows dimension independent programming.
478 */
479 Point<spacedim>
480 get_new_point_on_face(
481 const typename Triangulation<dim, spacedim>::face_iterator &face) const;
482
483
484 /**
485 * Backward compatibility interface. Depending on <tt>dim=1</tt>,
486 * <tt>dim=2</tt> or <tt>dim=3</tt> this function calls the
487 * get_new_point_on_line, get_new_point_on_quad or the get_new_point_on_hex
488 * function. This wrapper allows dimension independent programming.
489 */
490 Point<spacedim>
491 get_new_point_on_cell(
492 const typename Triangulation<dim, spacedim>::cell_iterator &cell) const;
493
494 /** @} */
495
496 /**
497 * @name Computing tangent vectors
498 * @{
499 */
500
501 /**
502 * Return a vector that, at $\mathbf x_1$, is tangential to
503 * the geodesic that connects two points $\mathbf x_1,\mathbf x_2$. The
504 * geodesic is the shortest line between these two points, where "shortest" is
505 * defined via a metric specific to a particular implementation of this class
506 * in a derived class. For example, in the case of a FlatManifold, the
507 * shortest line between two points is just the straight line, and in this
508 * case the tangent vector is just the difference $\mathbf d=\mathbf
509 * x_2-\mathbf x_1$. On the other hand, for a manifold that describes a
510 * surface embedded in a higher dimensional space (e.g., the surface of a
511 * sphere), then the tangent vector is tangential to the surface, and
512 * consequently may point in a different direction than the straight line that
513 * connects the two points.
514 *
515 * While tangent vectors are often normalized to unit length, the vectors
516 * returned by this function are normalized as described in the introduction
517 * of this class. Specifically, if $\mathbf s(t)$ traces out the geodesic
518 * between the two points where $\mathbf x_1 = \mathbf s(0)$ and
519 * $\mathbf x_2 = \mathbf s(1)$, then the returned vector must equal
520 * $\mathbf s'(0)$. In other words, the norm of the returned vector also
521 * encodes, in some sense, the <i>length</i> of the geodesic because a curve
522 * $\mathbf s(t)$ must move "faster" if the two points it connects between
523 * arguments $t=0$ and $t=1$ are farther apart.
524 *
525 * The default implementation of this function approximates
526 * $\mathbf s'(0) \approx \frac{\mathbf s(\epsilon)-\mathbf x_1}{\epsilon}$
527 * for a small value of $\epsilon$, and the evaluation of $\mathbf
528 * s(\epsilon)$ is done by calling get_new_point(). If possible, derived
529 * classes should override this function by an implementation of the exact
530 * derivative.
531 *
532 * @param x1 The first point that describes the geodesic, and the one
533 * at which the "direction" is to be evaluated.
534 * @param x2 The second point that describes the geodesic.
535 * @return A "direction" vector tangential to the geodesic.
536 */
537 virtual Tensor<1, spacedim>
538 get_tangent_vector(const Point<spacedim> &x1,
539 const Point<spacedim> &x2) const;
540
541 /** @} */
542
543 /**
544 * @name Computing normal vectors
545 * @{
546 */
547
548 /**
549 * Return the normal vector to a face embedded in this manifold, at
550 * the point p. It is not required that the normals actually point
551 * outward from the domain even if the face iterator given points
552 * to a face on the boundary of the domain.
553 * If p is not in fact on the surface, but only
554 * close-by, try to return something reasonable, for example the
555 * normal vector at the surface point closest to p. (The point p
556 * will in fact not normally lie on the actual surface, but rather
557 * be a quadrature point mapped by some polynomial mapping; the
558 * mapped surface, however, will not usually coincide with the
559 * actual surface.)
560 *
561 * This function only makes sense if dim==spacedim because
562 * otherwise there is no unique normal vector but in fact a
563 * (spacedim-dim+1)-dimensional tangent space of vectors that
564 * are all both normal to the face and normal to the dim-dimensional
565 * surface that lives in spacedim-dimensional space. For example,
566 * think of a two-dimensional mesh that covers a two-dimensional
567 * surface in three-dimensional space. In that case, each
568 * face (edge) is one-dimensional, and there are two linearly independent
569 * vectors that are both normal to the edge: one is normal to the
570 * edge and tangent to the surface (intuitively, that would be the
571 * one that points from the current cell to the neighboring one,
572 * if the surface was locally flat), and the other one is rooted
573 * in the edge but points perpendicular to the surface (which is
574 * also perpendicular to the edge that lives within the surface).
575 * Thus, because there are no obviously correct semantics for this function
576 * if spacedim is greater than dim, the function will simply throw
577 * an error in that situation.
578 *
579 * The face iterator gives an indication which face this function is
580 * supposed to compute the normal vector for. This is useful if the
581 * boundary of the domain is composed of different nondifferential
582 * pieces (for example when using the FlatManifold class to
583 * approximate a geometry that is completely described by the coarse
584 * mesh, with piecewise (bi-)linear components between the vertices,
585 * but where the boundary may have a kink at the vertices itself).
586 *
587 * @note In 2d, the default implementation of this function computes the
588 * normal vector by taking the tangent direction from p to
589 * the further one of the two vertices that make up an edge, and then
590 * rotates it outward (with respect to the coordinate system of the edge)
591 * by 90 degrees. In 3d, the default implementation is more
592 * complicated, aiming at avoiding problems with numerical round-off
593 * for points close to one of the vertices, and avoiding tangent directions
594 * that are linearly dependent.
595 */
596 virtual Tensor<1, spacedim>
597 normal_vector(
598 const typename Triangulation<dim, spacedim>::face_iterator &face,
599 const Point<spacedim> &p) const;
600
601 /**
602 * Compute the normal vectors to the boundary at each vertex of the
603 * given face embedded in the Manifold. It is not required that the
604 * normal vectors be normed somehow. Neither is it required that
605 * the normals actually point outward.
606 *
607 * This function is needed to compute data for C1 mappings. The
608 * default implementation calls normal_vector() on each vertex.
609 *
610 * Note that when computing normal vectors at a vertex where the
611 * boundary is not differentiable, you have to make sure that you
612 * compute the one-sided limits, i.e. limit with respect to points
613 * inside the given face.
614 */
615 virtual void
616 get_normals_at_vertices(
617 const typename Triangulation<dim, spacedim>::face_iterator &face,
618 FaceVertexNormals &face_vertex_normals) const;
619
620 /** @} */
621 };
622
623
624 /**
625 * Specialization of Manifold<dim,spacedim>, which represent a possibly
626 * periodic Euclidean space of dimension @p dim embedded in the Euclidean
627 * space of @p spacedim dimensions. The main characteristic of this Manifold
628 * is the fact that the function
629 * FlatManifold<dim,spacedim>::project_to_manifold() is the identity function.
630 *
631 * @ingroup manifold
632 */
633 template <int dim, int spacedim = dim>
634 class FlatManifold : public Manifold<dim, spacedim>
635 {
636 public:
637 /**
638 * Default constructor. The optional argument can be used to specify the
639 * periodicity of the spacedim-dimensional manifold (one period per
640 * direction). A periodicity value of zero means that along that direction
641 * there is no periodicity. By default no periodicity is assumed.
642 *
643 * Periodicity affects the way a middle point is computed. It is assumed
644 * that if two points are more than half period distant, then the distance
645 * should be computed by crossing the periodicity boundary, i.e., the
646 * average is computed by adding a full period to the sum of the two. For
647 * example, if along direction 0 we have 2*pi periodicity, then the average
648 * of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero), since, on a
649 * periodic manifold, these two points are at distance 2*eps and not (2*pi-
650 * eps). Special cases are taken into account, to ensure that the behavior
651 * is always as expected. The third argument is used as a relative tolerance
652 * when computing distances.
653 *
654 * Periodicity will be intended in the following way: the domain is
655 * considered to be the box contained in [Point<spacedim>(), periodicity)
656 * where the right extreme is excluded. If any of the components of this box
657 * has zero length, then no periodicity is assumed in that direction.
658 * Whenever a function that tries to compute averages is called, an
659 * exception will be thrown if one of the points which you are using for the
660 * average lies outside the periodicity box. The return points are
661 * guaranteed to lie in the periodicity box plus or minus
662 * tolerance*periodicity.norm().
663 */
664 FlatManifold(const Tensor<1, spacedim> &periodicity = Tensor<1, spacedim>(),
665 const double tolerance = 1e-10);
666
667 /**
668 * Return a copy of this manifold.
669 */
670 virtual std::unique_ptr<Manifold<dim, spacedim>>
671 clone() const override;
672
673 /**
674 * Let the new point be the average sum of surrounding vertices.
675 *
676 * This particular implementation constructs the weighted average of the
677 * surrounding points, and then calls internally the function
678 * project_to_manifold(). The reason why we do it this way, is to allow lazy
679 * programmers to implement only the project_to_manifold() function for their
680 * own Manifold classes which are small (or trivial) perturbations of a flat
681 * manifold. This is the case whenever the coarse mesh is a decent
682 * approximation of the manifold geometry. In this case, the middle point of
683 * a cell is close to true middle point of the manifold, and a projection
684 * may suffice.
685 *
686 * For most simple geometries, it is possible to get reasonable results by
687 * deriving your own Manifold class from FlatManifold, and write a new
688 * interface only for the project_to_manifold function. You will have good
689 * approximations also with large deformations, as long as in the coarsest
690 * mesh size you are trying to refine, the middle point is not too far from
691 * the manifold mid point, i.e., as long as the coarse mesh size is small
692 * enough.
693 */
694 virtual Point<spacedim>
695 get_new_point(const ArrayView<const Point<spacedim>> &surrounding_points,
696 const ArrayView<const double> &weights) const override;
697
698
699 /**
700 * Compute a new set of points that interpolate between the given points @p
701 * surrounding_points. @p weights is a table with as many columns as @p
702 * surrounding_points.size(). The number of rows in @p weights must match
703 * the length of @p new_points.
704 *
705 * For this particular implementation, the interpolation of the
706 * @p surrounding_points according to the @p weights is simply performed in
707 * Cartesian space.
708 */
709 virtual void
710 get_new_points(const ArrayView<const Point<spacedim>> &surrounding_points,
711 const Table<2, double> &weights,
712 ArrayView<Point<spacedim>> new_points) const override;
713
714 /**
715 * Project to FlatManifold. This is the identity function for flat,
716 * Euclidean spaces. Note however that this function can be overloaded by
717 * derived classes, which will then benefit from the logic behind the
718 * get_new_point() function which are often very similar (if not identical) to
719 * the one implemented in this class.
720 */
721 virtual Point<spacedim>
722 project_to_manifold(const ArrayView<const Point<spacedim>> &points,
723 const Point<spacedim> &candidate) const override;
724
725 /**
726 * Return a vector that, at $\mathbf x_1$, is tangential to
727 * the geodesic that connects two points $\mathbf x_1,\mathbf x_2$.
728 * For the current class, we assume that the manifold is flat, so
729 * the geodesic is the straight line between the two points, and we
730 * return $\mathbf x_2-\mathbf x_1$. The normalization of the vector
731 * is chosen so that it fits the convention described in
732 * Manifold::get_tangent_vector().
733 *
734 * @note If you use this class as a stepping stone to build a manifold
735 * that only "slightly" deviates from a flat manifold, by overloading
736 * the project_to_manifold() function.
737 *
738 * @param x1 The first point that describes the geodesic, and the one
739 * at which the "direction" is to be evaluated.
740 * @param x2 The second point that describes the geodesic.
741 * @return A "direction" vector tangential to the geodesic. Here, this is
742 * $\mathbf x_2-\mathbf x_1$, possibly modified by the periodicity of
743 * the domain as set in the constructor, to use the "shortest" connection
744 * between the points through the periodic boundary as necessary.
745 */
746 virtual Tensor<1, spacedim>
747 get_tangent_vector(const Point<spacedim> &x1,
748 const Point<spacedim> &x2) const override;
749
750 /**
751 * Return the normal vector to the given face at point p taking into account
752 * that quadrilateral faces of hexahedral cells in 3d may not be planar.
753 * In those cases, the face is assumed to have a geometry described by a
754 * bilinear function, and the normal vector is computed by embedding this
755 * bilinear form into a Cartesian space with a flat metric.
756 */
757 virtual Tensor<1, spacedim>
758 normal_vector(
759 const typename Triangulation<dim, spacedim>::face_iterator &face,
760 const Point<spacedim> &p) const override;
761
762 /**
763 * Compute the normal vectors to the boundary at each vertex of the
764 * given face taking into account that quadrilateral faces of hexahedral
765 * cells in 3d may not be planar. In those cases, the face is assumed to
766 * have a geometry described by a bilinear function, and the normal vector
767 * is computed by embedding this bilinear form into a Cartesian space with
768 * a flat metric.
769 */
770 virtual void
771 get_normals_at_vertices(
772 const typename Triangulation<dim, spacedim>::face_iterator &face,
773 typename Manifold<dim, spacedim>::FaceVertexNormals &face_vertex_normals)
774 const override;
775
776 /**
777 * Return the periodicity of this Manifold.
778 */
779 const Tensor<1, spacedim> &
780 get_periodicity() const;
781
782 /**
783 * Return the relative tolerance set in the constructor.
784 */
785 double
786 get_tolerance() const;
787
788 private:
789 /**
790 * The periodicity of this Manifold. Periodicity affects the way a middle
791 * point is computed. It is assumed that if two points are more than half
792 * period distant, then the distance should be computed by crossing the
793 * periodicity boundary, i.e., the average is computed by adding a full
794 * period to the sum of the two. For example, if along direction 0 we have
795 * 2*pi periodicity, then the average of (2*pi-eps) and (eps) is not pi, but
796 * 2*pi (or zero), since, on a periodic manifold, these two points are at
797 * distance 2*eps and not (2*pi-eps).
798 *
799 * A periodicity 0 along one direction means no periodicity. This is the
800 * default value for all directions.
801 */
802 const Tensor<1, spacedim> periodicity;
803
804 DeclException3(ExcPeriodicBox,
805 int,
806 Point<spacedim>,
807 double,
808 << "The component number " << arg1 << " of the point [ "
809 << arg2 << " ] is not in the interval [ 0, " << arg3
810 << "), bailing out.");
811
812 /**
813 * Relative tolerance. This tolerance is used to compute distances in double
814 * precision.
815 */
816 const double tolerance;
817 };
818
819
820 /**
821 * This class describes mappings that can be expressed in terms of charts.
822 * Specifically, this class with its template arguments describes a chart of
823 * dimension chartdim, which is part of a Manifold<dim,spacedim> and is used
824 * in an object of type Triangulation<dim,spacedim>: It specializes a
825 * Manifold of dimension chartdim embedded in a manifold of dimension
826 * spacedim, for which you have explicit pull_back() and push_forward()
827 * transformations. Its use is explained in great detail in step-53.
828 *
829 * This is a helper class which is useful when you have an explicit map from
830 * an Euclidean space of dimension chartdim to an Euclidean space of dimension
831 * spacedim which represents your manifold, i.e., when your manifold
832 * $\mathcal{M}$ can be represented by a map \f[ F: \mathcal{B} \subset
833 * R^{\text{chartdim}} \mapsto \mathcal{M} \subset R^{\text{spacedim}} \f]
834 * (the push_forward() function) and that admits the inverse transformation
835 * \f[ F^{-1}: \mathcal{M} \subset R^{\text{spacedim}} \mapsto \mathcal{B}
836 * \subset R^{\text{chartdim}} \f] (the pull_back() function).
837 *
838 * The get_new_point() function of the ChartManifold class is implemented by
839 * calling the pull_back() method for all <tt>surrounding_points</tt>,
840 * computing their weighted average in the chartdim Euclidean space, and
841 * calling the push_forward() method with the resulting point, i.e., \f[
842 * \mathbf x^{\text{new}} = F(\sum_i w_i F^{-1}(\mathbf x_i)). \f]
843 *
844 * Derived classes are required to implement the push_forward() and the
845 * pull_back() methods. All other functions (with the exception of the
846 * push_forward_gradient() function, see below) that are required by mappings
847 * will then be provided by this class.
848 *
849 *
850 * <h3>Providing function gradients</h3>
851 *
852 * In order to compute vectors that are tangent to the manifold (for example,
853 * tangent to a surface embedded in higher dimensional space, or simply the
854 * three unit vectors of ${\mathbb R}^3$), one needs to also have access
855 * to the <i>gradient</i> of the push-forward function $F$. The gradient
856 * is the matrix $(\nabla F)_{ij}=\partial_j F_i$, where we take the derivative
857 * with regard to the chartdim reference coordinates on the flat Euclidean
858 * space in which $\mathcal B$ is located. In other words, at a point
859 * $\mathbf x$, $\nabla F(\mathbf x)$ is a matrix of size @p spacedim
860 * times @p chartdim.
861 *
862 * Only the ChartManifold::get_tangent_vector() function uses the gradient
863 * of the push-forward, but only a subset of all finite element codes
864 * actually require the computation of tangent vectors. Consequently,
865 * while derived classes need to implement the abstract virtual push_forward()
866 * and pull_back() functions of this class, they do not need to implement
867 * the virtual push_forward_gradient() function. Rather, that function has a
868 * default implementation (and consequently is not abstract, therefore not
869 * forcing derived classes to overload it), but the default implementation
870 * clearly can not compute anything useful and therefore simply triggers
871 * and exception.
872 *
873 *
874 * <h3>A note on the template arguments</h3>
875 *
876 * The dimension arguments @p chartdim, @p dim and @p spacedim must satisfy
877 * the following relationships:
878 * @code
879 * dim <= spacedim
880 * chartdim <= spacedim
881 * @endcode
882 * However, there is no a priori relationship between @p dim and @p chartdim.
883 * For example, if you want to describe a mapping for an edge (a 1d object) in
884 * a 2d triangulation embedded in 3d space, you could do so by parameterizing
885 * it via a line
886 * @f[
887 * F: [0,1] \rightarrow {\mathbb R}^3
888 * @f]
889 * in which case @p chartdim is 1. On the other hand, there is no reason why
890 * one can't describe this as a mapping
891 * @f[
892 * F: {\mathbb R}^3 \rightarrow {\mathbb R}^3
893 * @f]
894 * in such a way that the line $[0,1]\times \{0\}\times \{0\}$ happens to be
895 * mapped onto the edge in question. Here, @p chartdim is 3. This may seem
896 * cumbersome but satisfies the requirements of an invertible function $F$
897 * just fine as long as it is possible to get from the edge to the pull-back
898 * space and then back again. Finally, given that we are dealing with a 2d
899 * triangulation in 3d, one will often have a mapping from, say, the 2d unit
900 * square or unit disk to the domain in 3d space, and the edge in question may
901 * simply be the mapped edge of the unit domain in 2d space. In this case, @p
902 * chartdim is 2.
903 *
904 * @ingroup manifold
905 */
906 template <int dim, int spacedim = dim, int chartdim = dim>
907 class ChartManifold : public Manifold<dim, spacedim>
908 {
909 public:
910 // explicitly check for sensible template arguments
911 static_assert(dim <= spacedim,
912 "The dimension <dim> of a ChartManifold must be less than or "
913 "equal to the space dimension <spacedim> in which it lives.");
914
915 /**
916 * Constructor. The optional argument can be used to specify the periodicity
917 * of the chartdim-dimensional manifold (one period per direction). A
918 * periodicity value of zero means that along that direction there is no
919 * periodicity. By default no periodicity is assumed.
920 *
921 * Periodicity affects the way a middle point is computed. It is assumed
922 * that if two points are more than half period distant, then the distance
923 * should be computed by crossing the periodicity boundary, i.e., then the
924 * average is computed by adding a full period to the sum of the two. For
925 * example, if along direction 0 we have 2*pi periodicity, then the average
926 * of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero), since, on the
927 * manifold, these two points are at distance 2*eps and not (2*pi-eps)
928 */
929 ChartManifold(const Tensor<1, chartdim> &periodicity = Tensor<1, chartdim>());
930
931 /**
932 * Destructor. Does nothing here, but needs to be declared to make it
933 * virtual.
934 */
935 virtual ~ChartManifold() override = default;
936
937 /**
938 * Refer to the general documentation of this class and the documentation of
939 * the base class for more information.
940 */
941 virtual Point<spacedim>
942 get_intermediate_point(const Point<spacedim> &p1,
943 const Point<spacedim> &p2,
944 const double w) const override;
945
946 /**
947 * Refer to the general documentation of this class and the documentation of
948 * the base class for more information.
949 */
950 virtual Point<spacedim>
951 get_new_point(const ArrayView<const Point<spacedim>> &surrounding_points,
952 const ArrayView<const double> &weights) const override;
953
954 /**
955 * Compute a new set of points that interpolate between the given points @p
956 * surrounding_points. @p weights is a table with as many columns as @p
957 * surrounding_points.size(). The number of rows in @p weights must match
958 * the length of @p new_points.
959 *
960 * The implementation of this function first transforms the
961 * @p surrounding_points to the chart space by calling pull_back(). Then, new
962 * points are computed on the chart by usual interpolation according to the
963 * given @p weights, which are finally transformed to the image space by
964 * push_forward().
965 *
966 * This implementation can be much more efficient for computing multiple new
967 * points from the same surrounding points than separate calls to
968 * get_new_point() in case the pull_back() operation is expensive. This is
969 * because pull_back() is only called once for the surrounding points and
970 * the interpolation is done for all given weights using this set of
971 * points. Often, pull_back() is also more expensive than push_forward()
972 * because the former might involve some kind of Newton iteration in
973 * non-trivial manifolds.
974 */
975 virtual void
976 get_new_points(const ArrayView<const Point<spacedim>> &surrounding_points,
977 const Table<2, double> &weights,
978 ArrayView<Point<spacedim>> new_points) const override;
979 /**
980 * Pull back the given point in spacedim to the Euclidean chartdim
981 * dimensional space.
982 *
983 * Refer to the general documentation of this class for more information.
984 */
985 virtual Point<chartdim>
986 pull_back(const Point<spacedim> &space_point) const = 0;
987
988 /**
989 * Given a point in the chartdim dimensional Euclidean space, this method
990 * returns a point on the manifold embedded in the spacedim Euclidean space.
991 *
992 * Refer to the general documentation of this class for more information.
993 */
994 virtual Point<spacedim>
995 push_forward(const Point<chartdim> &chart_point) const = 0;
996
997 /**
998 * Given a point in the chartdim dimensional Euclidean space, this method
999 * returns the derivatives of the function $F$ that maps from the
1000 * chartdim-dimensional to the spacedim-dimensional space. In other
1001 * words, it is a matrix of size $\text{spacedim}\times\text{chartdim}$.
1002 *
1003 * This function is used in the computations required by the
1004 * get_tangent_vector() function. Since not all users of the Manifold
1005 * class interface will require calling that function, the current
1006 * function is implemented but will trigger an exception whenever
1007 * called. This allows derived classes to avoid implementing the
1008 * push_forward_gradient function if this functionality is not
1009 * needed in the user program.
1010 *
1011 * Refer to the general documentation of this class for more information.
1012 */
1013 virtual DerivativeForm<1, chartdim, spacedim>
1014 push_forward_gradient(const Point<chartdim> &chart_point) const;
1015
1016 /**
1017 * Return a vector that, at $\mathbf x_1$, is tangential to
1018 * the geodesic that connects two points $\mathbf x_1,\mathbf x_2$.
1019 * See the documentation of the Manifold class and of
1020 * Manifold::get_tangent_vector() for a more detailed description.
1021 *
1022 * For the current class, we assume that this geodesic is the image
1023 * under the push_forward() operation of a straight line of the
1024 * pre-images of @p x1 and @p x2 (where pre-images are computed by pulling
1025 * back the locations @p x1 and @p x2). In other words, if these
1026 * preimages are $\xi_1=F^{-1}(\mathbf x_1), \xi_2=F^{-1}(\mathbf x_2)$,
1027 * then the geodesic in preimage (the chartdim-dimensional Euclidean) space
1028 * is
1029 * @f{align*}{
1030 * \zeta(t) &= \xi_1 + t (\xi_2-\xi_1)
1031 * \\ &= F^{-1}(\mathbf x_1) + t\left[F^{-1}(\mathbf x_2)
1032 * -F^{-1}(\mathbf x_1)\right]
1033 * @f}
1034 * In image space, i.e., in the space in which we operate, this
1035 * leads to the curve
1036 * @f{align*}{
1037 * \mathbf s(t) &= F(\zeta(t))
1038 * \\ &= F(\xi_1 + t (\xi_2-\xi_1))
1039 * \\ &= F\left(F^{-1}(\mathbf x_1) + t\left[F^{-1}(\mathbf x_2)
1040 * -F^{-1}(\mathbf x_1)\right]\right).
1041 * @f}
1042 * What the current function is supposed to return is $\mathbf s'(0)$. By
1043 * the chain rule, this is equal to
1044 * @f{align*}{
1045 * \mathbf s'(0) &=
1046 * \frac{d}{dt}\left. F\left(F^{-1}(\mathbf x_1)
1047 * + t\left[F^{-1}(\mathbf x_2)
1048 * -F^{-1}(\mathbf x_1)\right]\right)
1049 * \right|_{t=0}
1050 * \\ &= \nabla_\xi F\left(F^{-1}(\mathbf x_1)\right)
1051 * \left[F^{-1}(\mathbf x_2)
1052 * -F^{-1}(\mathbf x_1)\right].
1053 * @f}
1054 * This formula may then have to be slightly modified by
1055 * considering any periodicity that was assumed in the call to
1056 * the constructor.
1057 *
1058 * Thus, the computation of tangent vectors also requires the
1059 * implementation of <i>derivatives</i> $\nabla_\xi F(\xi)$ of
1060 * the push-forward mapping. Here, $F^{-1}(\mathbf x_2)-F^{-1}(\mathbf x_1)$
1061 * is a chartdim-dimensional vector, and $\nabla_\xi F\left(F^{-1}(\mathbf
1062 * x_1)\right) = \nabla_\xi F\left(\xi_1\right)$ is a
1063 * spacedim-times-chartdim-dimensional matrix. Consequently, and as desired,
1064 * the operation results in a spacedim-dimensional vector.
1065 *
1066 * @param x1 The first point that describes the geodesic, and the one
1067 * at which the "direction" is to be evaluated.
1068 * @param x2 The second point that describes the geodesic.
1069 * @return A "direction" vector tangential to the geodesic.
1070 */
1071 virtual Tensor<1, spacedim>
1072 get_tangent_vector(const Point<spacedim> &x1,
1073 const Point<spacedim> &x2) const override;
1074
1075 /**
1076 * Return the periodicity associated with the submanifold.
1077 */
1078 const Tensor<1, chartdim> &
1079 get_periodicity() const;
1080
1081 private:
1082 /**
1083 * The sub_manifold object is used to compute the average of the points in
1084 * the chart coordinates system.
1085 *
1086 * In an ideal world, it would have type
1087 * FlatManifold<dim,chartdim>. However, this would instantiate cases
1088 * where dim>spacedim, which leads to invalid situations. We instead
1089 * use <chartdim,chartdim>, which is (i) always valid, and (ii) does
1090 * not matter at all since the first (dim) argument of manifolds is,
1091 * in fact, ignored as far as manifold functionality is concerned.
1092 */
1093 const FlatManifold<chartdim, chartdim> sub_manifold;
1094 };
1095
1096
1097 /* -------------- declaration of explicit specializations ------------- */
1098
1099 #ifndef DOXYGEN
1100
1101 template <>
1102 Point<1>
1103 Manifold<1, 1>::get_new_point_on_face(
1104 const Triangulation<1, 1>::face_iterator &) const;
1105
1106 template <>
1107 Point<2>
1108 Manifold<1, 2>::get_new_point_on_face(
1109 const Triangulation<1, 2>::face_iterator &) const;
1110
1111
1112 template <>
1113 Point<3>
1114 Manifold<1, 3>::get_new_point_on_face(
1115 const Triangulation<1, 3>::face_iterator &) const;
1116
1117
1118 template <>
1119 Point<1>
1120 Manifold<1, 1>::get_new_point_on_quad(
1121 const Triangulation<1, 1>::quad_iterator &) const;
1122
1123 template <>
1124 Point<2>
1125 Manifold<1, 2>::get_new_point_on_quad(
1126 const Triangulation<1, 2>::quad_iterator &) const;
1127
1128
1129 template <>
1130 Point<3>
1131 Manifold<1, 3>::get_new_point_on_quad(
1132 const Triangulation<1, 3>::quad_iterator &) const;
1133
1134
1135 template <>
1136 Point<3>
1137 Manifold<3, 3>::get_new_point_on_hex(
1138 const Triangulation<3, 3>::hex_iterator &) const;
1139
1140 /*---Templated functions---*/
1141
1142 template <int dim, int spacedim>
1143 inline double
1144 FlatManifold<dim, spacedim>::get_tolerance() const
1145 {
1146 return tolerance;
1147 }
1148
1149
1150
1151 namespace Manifolds
1152 {
1153 template <typename MeshIteratorType>
1154 std::pair<std::array<Point<MeshIteratorType::AccessorType::space_dimension>,
1155 n_default_points_per_cell<MeshIteratorType>()>,
1156 std::array<double, n_default_points_per_cell<MeshIteratorType>()>>
1157 get_default_points_and_weights(const MeshIteratorType &iterator,
1158 const bool with_interpolation)
1159 {
1160 const int dim = MeshIteratorType::AccessorType::structure_dimension;
1161 const int spacedim = MeshIteratorType::AccessorType::space_dimension;
1162 constexpr std::size_t points_per_cell =
1163 n_default_points_per_cell<MeshIteratorType>();
1164
1165 std::pair<std::array<Point<spacedim>, points_per_cell>,
1166 std::array<double, points_per_cell>>
1167 points_weights;
1168
1169
1170 // note that the exact weights are chosen such as to minimize the
1171 // distortion of the four new quads from the optimal shape; their
1172 // derivation and values is copied over from the
1173 // interpolation function in the mapping
1174 switch (dim)
1175 {
1176 case 1:
1177 Assert(points_weights.first.size() == 2, ExcInternalError());
1178 Assert(points_weights.second.size() == 2, ExcInternalError());
1179 points_weights.first[0] = iterator->vertex(0);
1180 points_weights.second[0] = .5;
1181 points_weights.first[1] = iterator->vertex(1);
1182 points_weights.second[1] = .5;
1183 break;
1184 case 2:
1185 Assert(points_weights.first.size() == 8, ExcInternalError());
1186 Assert(points_weights.second.size() == 8, ExcInternalError());
1187
1188 for (unsigned int i = 0; i < 4; ++i)
1189 {
1190 points_weights.first[i] = iterator->vertex(i);
1191 points_weights.first[4 + i] =
1192 (iterator->line(i)->has_children() ?
1193 iterator->line(i)->child(0)->vertex(1) :
1194 iterator->line(i)->get_manifold().get_new_point_on_line(
1195 iterator->line(i)));
1196 }
1197
1198 if (with_interpolation)
1199 {
1200 std::fill(points_weights.second.begin(),
1201 points_weights.second.begin() + 4,
1202 -0.25);
1203 std::fill(points_weights.second.begin() + 4,
1204 points_weights.second.end(),
1205 0.5);
1206 }
1207 else
1208 std::fill(points_weights.second.begin(),
1209 points_weights.second.end(),
1210 1.0 / 8.0);
1211 break;
1212 case 3:
1213 {
1214 TriaIterator<TriaAccessor<3, 3, 3>> hex =
1215 static_cast<TriaIterator<TriaAccessor<3, 3, 3>>>(iterator);
1216 const unsigned int np = GeometryInfo<dim>::vertices_per_cell +
1217 GeometryInfo<dim>::lines_per_cell +
1218 GeometryInfo<dim>::faces_per_cell;
1219 Assert(points_weights.first.size() == np, ExcInternalError());
1220 Assert(points_weights.second.size() == np, ExcInternalError());
1221 auto *sp3 = reinterpret_cast<
1222 std::array<Point<3>, n_default_points_per_cell<decltype(hex)>()>
1223 *>(&points_weights.first);
1224
1225 unsigned int j = 0;
1226
1227 // note that the exact weights are chosen such as to minimize the
1228 // distortion of the eight new hexes from the optimal shape through
1229 // transfinite interpolation from the faces and vertices, see
1230 // TransfiniteInterpolationManifold for a deeper explanation of the
1231 // mechanisms
1232 if (with_interpolation)
1233 {
1234 for (unsigned int i = 0;
1235 i < GeometryInfo<dim>::vertices_per_cell;
1236 ++i, ++j)
1237 {
1238 (*sp3)[j] = hex->vertex(i);
1239 points_weights.second[j] = 1.0 / 8.0;
1240 }
1241 for (unsigned int i = 0; i < GeometryInfo<dim>::lines_per_cell;
1242 ++i, ++j)
1243 {
1244 (*sp3)[j] =
1245 (hex->line(i)->has_children() ?
1246 hex->line(i)->child(0)->vertex(1) :
1247 hex->line(i)->get_manifold().get_new_point_on_line(
1248 hex->line(i)));
1249 points_weights.second[j] = -1.0 / 4.0;
1250 }
1251 for (unsigned int i = 0; i < GeometryInfo<dim>::faces_per_cell;
1252 ++i, ++j)
1253 {
1254 (*sp3)[j] =
1255 (hex->quad(i)->has_children() ?
1256 hex->quad(i)->isotropic_child(0)->vertex(3) :
1257 hex->quad(i)->get_manifold().get_new_point_on_quad(
1258 hex->quad(i)));
1259 points_weights.second[j] = 1.0 / 2.0;
1260 }
1261 }
1262 else
1263 // Overwrite the weights with 1/np if we don't want to use
1264 // interpolation.
1265 std::fill(points_weights.second.begin(),
1266 points_weights.second.end(),
1267 1.0 / np);
1268 }
1269 break;
1270 default:
1271 DEAL_II_ASSERT_UNREACHABLE();
1272 break;
1273 }
1274 return points_weights;
1275 }
1276 } // namespace Manifolds
1277
1278 #endif // DOXYGEN
1279
1280 DEAL_II_NAMESPACE_CLOSE
1281
1282 #endif