From: Luca Heltai Date: Thu, 14 Jul 2016 16:06:22 +0000 (+0200) Subject: Updated documentation for Manifolds. X-Git-Tag: v8.5.0-rc1~806^2~3 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=87b0f6e1ff8393abbecd053b79810fafb19e3fe3;p=dealii.git Updated documentation for Manifolds. --- diff --git a/include/deal.II/grid/manifold.h b/include/deal.II/grid/manifold.h index bc6c4f3385..cf440ce88d 100644 --- a/include/deal.II/grid/manifold.h +++ b/include/deal.II/grid/manifold.h @@ -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 + * a 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 - get_new_point( const Point &p1, - const Point &p2, - const double w) const; + get_new_point (const Point &p1, + const Point &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 - get_new_point(const Quadrature &quad) const; + get_new_point (const Quadrature &quad) const; /** * Given a point which lies close to the given manifold, it modifies it and diff --git a/include/deal.II/grid/manifold_lib.h b/include/deal.II/grid/manifold_lib.h index 255bba0aa4..b390d44dc5 100644 --- a/include/deal.II/grid/manifold_lib.h +++ b/include/deal.II/grid/manifold_lib.h @@ -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