From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Fri, 2 Oct 2015 04:26:03 +0000 (-0500)
Subject: More doc updates.
X-Git-Tag: v8.4.0-rc2~349^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8dc4954a86a3934fefd14e0360a98185d9ca5a97;p=dealii.git

More doc updates.
---

diff --git a/include/deal.II/fe/mapping_q.h b/include/deal.II/fe/mapping_q.h
index f761d1c363..32eb88545d 100644
--- a/include/deal.II/fe/mapping_q.h
+++ b/include/deal.II/fe/mapping_q.h
@@ -57,7 +57,7 @@ template <int dim, typename POLY> class TensorProductPolynomials;
  *   achieve this by setting the second argument to the constructor
  *   to true. This only makes sense if you can actually provide
  *   information about how interior edges and faces of the mesh
- *   should be curved. This is typically done using by associating
+ *   should be curved. This is typically done by associating
  *   a Manifold with interior cells and edges. A simple example of this
  *   is discussed in the "Results" section of step-6; a full discussion
  *   of manifolds is provided in step-53.
diff --git a/include/deal.II/fe/mapping_q_generic.h b/include/deal.II/fe/mapping_q_generic.h
index a96dbcb9f7..923b4e9e8e 100644
--- a/include/deal.II/fe/mapping_q_generic.h
+++ b/include/deal.II/fe/mapping_q_generic.h
@@ -39,20 +39,53 @@ template <int,int> class MappingQ;
 
 
 /**
- * A base class for all polynomial mappings. In particular, this class
- * provides the basis for the MappingQ1 and MappingQ classes that
- * implement (bi-, tri-)linear mappings and higher order mappings,
- * respectively.
+ * This class implements the functionality for polynomial mappings
+ * $Q_p$ of polynomial degree $p$ that will be used on all cells of
+ * the mesh. The MappingQ1 and MappingQ classes specialize this
+ * behavior slightly.
  *
+ * The class is poorly named. It should really have been called
+ * MappingQ because it consistently uses $Q_p$ mappings on all cells
+ * of a triangulation. However, the name MappingQ was already taken
+ * when we rewrote the entire class hierarchy for mappings. One might
+ * argue that one should always use MappingQGeneric over the existing
+ * class MappingQ (which, unless explicitly specified during the
+ * construction of the object, only uses mappings of degree $p$ <i>on
+ * cells at the boundary of the domain</i>). On the other hand, there
+ * are good reasons to use MappingQ in many situations: in many
+ * situations, curved domains are only provided with information about
+ * how exactly edges at the boundary are shaped, but we do not know
+ * anything about internal edges. Thus, in the absence of other
+ * information, we can only assume that internal edges are straight
+ * lines, and in that case internal cells may as well be treated is
+ * bilinear quadrilaterals or trilinear hexahedra. (An example of how
+ * such meshes look is shown in step-1 already, but it is also
+ * discussed in the "Results" section of step-6.)  Because
+ * bi-/trilinear mappings are significantly cheaper to compute than
+ * higher order mappings, it is advantageous in such situations to use
+ * the higher order mapping only on cells at the boundary of the
+ * domain -- i.e., the behavior of MappingQ. Of course,
+ * MappingQGeneric also uses bilinear mappings for interior cells as
+ * long as it has no knowledge about curvature of interior edges, but
+ * it implements this the expensive way: as a general $Q_p$ mapping
+ * where the mapping support points just <i>happen</i> to be arranged
+ * along linear or bilinear edges or faces.
  *
- * <h3>Implementation</h3>
- *
- * This class provides essentially the entire generic infrastructure
- * for polynomial mappings. What it requires to work from derived
- * classes is an implementation of the
- * compute_mapping_support_points() class that provides a list of
- * locations to which the support points of the mapping (e.g., the
- * vertices of the cell in the lowest order case) should be mapped.
+ * There are a number of special cases worth considering:
+ * - If you really want to use a higher order mapping for all cells,
+ *   you can do this using the current class, but this only makes
+ *   sense if you can actually provide information about how interior
+ *   edges and faces of the mesh should be curved. This is typically
+ *   done by associating a Manifold with interior cells and
+ *   edges. A simple example of this is discussed in the "Results"
+ *   section of step-6; a full discussion of manifolds is provided in
+ *   step-53.
+ * - If you are working on meshes that describe a (curved) manifold
+ *   embedded in higher space dimensions, i.e., if dim!=spacedim, then
+ *   every cell is at the boundary of the domain you will likely
+ *   already have attached a manifold object to all cells that can
+ *   then also be used by the mapping classes for higher order
+ *   mappings.
  *
  *
  * @author Wolfgang Bangerth, 2015