From: heltai Date: Sun, 25 Aug 2013 13:39:16 +0000 (+0000) Subject: Better documented the Manifold class X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ba584c8de3a6260a0a52155ea7c1a33e1d67cfde;p=dealii-svn.git Better documented the Manifold class git-svn-id: https://svn.dealii.org/branches/branch_manifold_id@30479 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/include/deal.II/grid/manifold.h b/deal.II/include/deal.II/grid/manifold.h index c55367e249..4638b1d31a 100644 --- a/deal.II/include/deal.II/grid/manifold.h +++ b/deal.II/include/deal.II/grid/manifold.h @@ -18,7 +18,7 @@ #define __deal2__manifold_h -/*---------------------------- boundary-function.h ---------------------------*/ +/*---------------------------- manifold.h ---------------------------*/ #include #include @@ -68,16 +68,14 @@ class Manifold : public Subscriptor public: /** - * Destructor. Does nothing here, but - * needs to be declared to make it - * virtual. + * Destructor. Does nothing here, but needs to be declared to make + * it virtual. */ virtual ~Manifold (); /** - * Return the point which shall - * become the new vertex surrounded - * by the given points. + * Return the point which shall become the new vertex surrounded by + * the given points. */ virtual Point @@ -85,7 +83,7 @@ public: const std::vector &weights) const = 0; /** - * Return equally spaced intermediate points on between the given + * Return equally spaced intermediate points between the given * surrounding points. * * The number of points requested is given by the size of the vector @@ -97,14 +95,14 @@ public: * (which are thought to be the vertices of a quad), and an * exception is thrown if the number of requested points is not the * square of an integer number. The same is true if the number of - * surrounding points is 8: an exception is thrown if spacedim is - * not three, and the number of requested points is not the cube of - * an integer number. + * surrounding points is eight: an exception is thrown if spacedim + * is not three, and the number of requested points is not the cube + * of an integer number. * * This function is called by the @p MappingQ class, and it calls * internally the get_new_point class with appropriate weights, so - * that the user does not need to overload anything else. It is made - * virtual so that the user can overload it if the default + * that the user does not need, in general, to overload it. It is + * made virtual so that the user can overload it if the default * implementation is too slow. */ virtual @@ -113,12 +111,11 @@ public: const std::vector > &surrounding_points) const; /** - * Given a candidate point and a line segment characterized by the - * iterator, return a point that lies on the surface described by - * this object. This function is used in some mesh smoothing - * algorithms that try to move around points in order to improve the - * mesh quality but need to ensure that points that were on the - * boundary remain on the boundary. + * Given a point which lies close to the given manifold, it modifies + * it and projects it to manifold itself. This function is used in + * some mesh smoothing algorithms that try to move around points in + * order to improve the mesh quality but need to ensure that points + * that were on the manfold remain on the manifold. * * Derived classes do not need to implement this function unless * mesh smoothing algorithms are used with a particular boundary @@ -132,9 +129,8 @@ public: /** - * Specialization of Manifold, which places the new point - * right into the middle of the given points. The middle is defined - * as the weighted mean of the points. + * Specialization of Manifold, which represent the + * euclidean space of dimension #spacedim. * * @ingroup manifold * @@ -145,30 +141,24 @@ class FlatManifold: public Manifold { public: /** - * Default constructor. Some - * compilers require this for - * some reasons. + * Default constructor. Some compilers require this for some + * reasons. */ FlatManifold (); /** - * Let the new point be the - * arithmetic mean of the two - * vertices of the line. + * Let the new point be the average sum of surrounding vertices. * - * Refer to the general - * documentation of this class - * and the documentation of the - * base class for more - * information. + * Refer to the general documentation of this class and the + * documentation of the base class for more information. */ virtual Point get_new_point(const std::vector > &surrounding_points, const std::vector &weights) const; - /** - Project to FlatManifold: do nothing. - */ + /** + * Project to FlatManifold: do nothing. + */ virtual void project_to_manifold (Point &candidate) const; }; @@ -177,9 +167,38 @@ public: /** * A chart of dimension dim, which is part of a Manifold. * This object specializes a Manifold of dimension dim embedded in a - * manifold of dimension spacedim, for which you have an explicit + * manifold of dimension spacedim, for which you have explicit * pull_back and push_forward transformations. * + * This is an helper class which is useful when you have an explicit + * map from an Euclidean space of dimension dim to an Euclidean + * space of dimension spacedim which represent your manifold, i.e., + * when your manifold \f$\mathcal{M}\f$ can be represented by a map + * \f[ + * F: \mathcal{B} \subset R^{\text{dim}} \mapsto \mathcal{M} + * \subset R^{\text{spacedim}} + * \f] + * (the push_forward() function) + * which admits the inverse transformation + * \f[ + * F^{-1}: \mathcal{M} + * \subset R^{\text{spacedim}} \mapsto + * \mathcal{B} \subset R^{\text{dim}} + * \f] + * (the pull_back() function). + * + * The get_new_point() function of the ManifoldChart class is + * implemented by calling the pull_back() method for all + * #surrounding_points, computing their weighted average in the dim + * Euclidean space, and calling the push_forward() method with the + * resulting point, i.e., + * \f[ + * p^{\text{new}} = F(\sum_i w_i F^{-1}(p_i)). + * \f] + * + * Derived classes are required to implement the push_forward() and + * the pull_back() methods. + * * @ingroup manifold * * @author Luca Heltai, 2013 @@ -190,31 +209,38 @@ class ManifoldChart: public Manifold public: /** - * Destructor. Does nothing here, but - * needs to be declared to make it - * virtual. + * Destructor. Does nothing here, but needs to be declared to make + * it virtual. */ virtual ~ManifoldChart (); /** - * Let the new point be the - * arithmetic mean of the two - * vertices of the line. - * - * Refer to the general - * documentation of this class - * and the documentation of the - * base class for more - * information. + * Refer to the general documentation of this class and the + * documentation of the base class for more information. */ virtual Point get_new_point(const std::vector > &surrounding_points, const std::vector &weights) const; + /** + * Pull back the given point in spacedim to the euclidean dim + * dimensional space. + * + * Refer to the general documentation of this class for more + * information. + */ virtual Point pull_back(const Point space_point) const = 0; + /** + * Given a point in the dim dimensianal Euclidean space, this + * method returns a point on the manifold embedded in the spacedim + * Euclidean space. + * + * Refer to the general documentation of this class for more + * information. + */ virtual Point push_forward(const Point chart_point) const = 0;