| 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> ¢er, |
| 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 |