]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Updated documentation for Manifolds.
authorLuca Heltai <luca.heltai@sissa.it>
Thu, 14 Jul 2016 16:06:22 +0000 (18:06 +0200)
committerLuca Heltai <luca.heltai@sissa.it>
Thu, 4 Aug 2016 08:44:10 +0000 (10:44 +0200)
include/deal.II/grid/manifold.h
include/deal.II/grid/manifold_lib.h

index bc6c4f33853a677ef8566c2d14ca27805c4f87ab..cf440ce88d510714f2006275d78339b0a57e4d83 100644 (file)
@@ -274,9 +274,9 @@ public:
 
   /**
    * Return an intermediate point between two given
-   * points. Overloading this function allows the default recursive
-   * implementation of the method get_new_point() that takes a
-   * Quadrature object as input to work properly.
+   * points. Overloading this function allows the default pair-wise
+   * reduction implementation of the method get_new_point() that takes
+   * Quadrature object as input to work properly.
    *
    * An implementation of this function should returns a parametric
    * curve on the manifold, joining the points `p1` and `p2`, with
@@ -291,9 +291,9 @@ public:
    */
   virtual
   Point<spacedim>
-  get_new_point(  const Point<spacedim> &p1,
-                  const Point<spacedim> &p2,
-                  const double w) const;
+  get_new_point (const Point<spacedim> &p1,
+                 const Point<spacedim> &p2,
+                 const double w) const;
 
   /**
    * Return the point which shall become the new vertex surrounded by the
@@ -301,13 +301,17 @@ public:
    * which should be filled with the surrounding points together with
    * appropriate weights.
    *
-   * In its default implementation it calls recursively the function
-   * get_new_point(). User classes can get away by simply implementing
-   * that method.
+   * In its default implementation it uses a pair-wise reduction of
+   * the points in the quadrature formula by calling the function
+   * get_new_point() that takes three arguments on the first two
+   * points, then on the resulting point and the next, untill all
+   * points in the quadrature have been taken into account. User
+   * classes can get away by simply implementing the get_new_point()
+   * function that takes three arguments.
    */
   virtual
   Point<spacedim>
-  get_new_point(const Quadrature<spacedim> &quad) const;
+  get_new_point (const Quadrature<spacedim> &quad) const;
 
   /**
    * Given a point which lies close to the given manifold, it modifies it and
index 255bba0aa4f442b23de685195a406727866f80bf..b390d44dc5388f144291030f3fd24e6fae7a9bfb 100644 (file)
@@ -129,9 +129,13 @@ private:
  *
  * While PolarManifold reflects the usual notion of polar coordinates,
  * it may not be suitable for domains that contain either the north or
- * south poles.
- * Consider for istance the pair of points \f$x_1=(1,\pi/3,0)\f$ and
- * \f$x_2=(1,\pi/3,\pi)\f$.
+ * south poles.  Consider for instance the pair of points
+ * \f$x_1=(1,\pi/3,0)\f$ and \f$x_2=(1,\pi/3,\pi)\f$ in polar
+ * coordinates (laying on the surface of a sphere with radius one, on
+ * a parallel at at height $\pi/3$. In this case connecting the points
+ * with a straight line in polar coordinates would take the long road
+ * around the globe, without passing through the north pole.
+ *
  * These two points would be connented (using a PolarManifold) by the curve
  * \$[
  * \begin{align}
@@ -139,7 +143,7 @@ private:
  *           t & \mapsto     &  (1,\pi/3,0) + (0,0,t\pi)
  * \$]
  * This curve is not a geodesic on the sphere, and it is not how we
- * would choose a curve on the sphere. A better one would be the one
+ * would connect those two points. A better curve, would be the one
  * passing through the North pole:
  * \[
  *  s(t) = x_1 \cos(\alpha(t)) + \kappa \times x_1 \sin(\alpha(t)) +
@@ -150,15 +154,22 @@ private:
  * Indeed, this is a geodesic, and it is the natural choice when
  * connecting points on the surface of the sphere.
  *
- * This class implements a Manifold that joins any two points in space
- * by first projecting them on the surface of a sphere with unit
- * radius, then connecting them with a geodesic, and finally rescaling
- * the final radius so that the resulting one is the weighted average
- * of the starting radii. This Manifold is identical to PolarManifold
- * in dimension two, while for dimension three it returns points that
- * are more uniformly distributed on the sphere, and it is invariant
- * with respect to rotations of the coordinate system, therefore
- * avoiding the problems that PolarManifold has at the poles.
+ * If the codimension of the Manifold is one, than this Manifold
+ * connects points using geodesics. In all other cases it is a
+ * continuus extension of the codimension one case.
+ *
+ * In particular, this class implements a Manifold that joins any two
+ * points in space by first projecting them onto the surface of a
+ * sphere with unit radius, then connecting them with a geodesic, and
+ * finally rescaling the final radius so that the resulting one is the
+ * weighted average of the starting radii. This Manifold is identical
+ * to PolarManifold in dimension two, while for dimension three it
+ * returns points that are more uniformly distributed on the sphere,
+ * and it is invariant with respect to rotations of the coordinate
+ * system, therefore avoiding the problems that PolarManifold has at
+ * the poles. Notice, in particular, that computing tangent vectors at
+ * the poles with a PolarManifold is not well defined, while it is
+ * perfectly fine with this class.
  *
  * For mathematical reasons, it is impossible to construct a unique
  * map of a sphere using only geodesic curves, and therefore, using
@@ -166,6 +177,15 @@ private:
  * Manifold to describe the geometry of a sphere, you should use
  * MappingQ as the underlying mapping, and not MappingManifold.
  *
+ * This Manifold can be used *only* on geometries where a finite ball
+ * is removed from the center. Indeed, the center is a singular point
+ * for this manifold, and if you try to connect two points across the
+ * center, they would travel on spherical coordinates, avoiding the
+ * center.
+ *
+ * The ideal geometry for this Manifold is an HyperShell. If you plan
+ * to use this Manifold on a Sphere
+ *
  * @ingroup manifold
  *
  * @author Mauro Bardelloni, Luca Heltai, 2016

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.