]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Remove mention of MappingQ1 from the documentation.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 7 Oct 2015 19:46:47 +0000 (14:46 -0500)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Thu, 8 Oct 2015 11:30:20 +0000 (06:30 -0500)
In preparation to possibly deprecating MappingQ1 in favor of MappingQGeneric(1),
remove all mentions of MappingQ1 from the documentation.

13 files changed:
include/deal.II/fe/fe_values.h
include/deal.II/fe/mapping.h
include/deal.II/fe/mapping_q.h
include/deal.II/fe/mapping_q1.h
include/deal.II/fe/mapping_q_generic.h
include/deal.II/grid/grid_out.h
include/deal.II/grid/tria_boundary.h
include/deal.II/hp/fe_values.h
include/deal.II/hp/mapping_collection.h
include/deal.II/matrix_free/fe_evaluation.h
include/deal.II/matrix_free/mapping_data_on_the_fly.h
include/deal.II/numerics/matrix_tools.h
include/deal.II/numerics/vector_tools.h

index 62a7fa76a820eea2ba3304bfa3a0534d44085a38..6aa158317047c1427e9979cda13b18cb39659551 100644 (file)
@@ -2796,7 +2796,9 @@ public:
             const UpdateFlags                  update_flags);
 
   /**
-   * Constructor. Uses MappingQ1 implicitly.
+   * Constructor. This constructor is equivalent to the other one except
+   * that it makes the object use a $Q_1$ mapping (i.e., an object of
+   * type MappingQGeneric(1)) implicitly.
    */
   FEValues (const FiniteElement<dim,spacedim> &fe,
             const Quadrature<dim>             &quadrature,
@@ -3005,7 +3007,9 @@ public:
                 const UpdateFlags                  update_flags);
 
   /**
-   * Constructor. Uses MappingQ1 implicitly.
+   * Constructor. This constructor is equivalent to the other one except
+   * that it makes the object use a $Q_1$ mapping (i.e., an object of
+   * type MappingQGeneric(1)) implicitly.
    */
   FEFaceValues (const FiniteElement<dim,spacedim> &fe,
                 const Quadrature<dim-1>           &quadrature,
@@ -3113,7 +3117,9 @@ public:
                    const UpdateFlags         update_flags);
 
   /**
-   * Constructor. Uses MappingQ1 implicitly.
+   * Constructor. This constructor is equivalent to the other one except
+   * that it makes the object use a $Q_1$ mapping (i.e., an object of
+   * type MappingQGeneric(1)) implicitly.
    */
   FESubfaceValues (const FiniteElement<dim,spacedim> &fe,
                    const Quadrature<dim-1>  &face_quadrature,
index 3a99fbc5422339417bbf935aecb170f8fb16c67b..5e236ffd41ee09a6b1ddb56f9d8aa8932b4699cd 100644 (file)
@@ -326,8 +326,8 @@ public:
    * triangulation).
    *
    * For example, implementations in derived classes return @p true for
-   * MappingQ, MappingQ1, MappingCartesian, but @p false for MappingQEulerian,
-   * MappingQ1Eulerian, and MappingFEField.
+   * MappingQ, MappingQGeneric, MappingCartesian, but @p false for
+   * MappingQEulerian, MappingQ1Eulerian, and MappingFEField.
    */
   virtual
   bool preserves_vertex_locations () const = 0;
index 8c44597f286806eb8d4ebdefe485e5994741b46e..86447fc6fe97f3d1f4c6cb6e5fed9a4283d8cf1c 100644 (file)
@@ -18,7 +18,6 @@
 
 
 #include <deal.II/base/config.h>
-#include <deal.II/fe/mapping_q1.h>
 #include <deal.II/fe/mapping_q_generic.h>
 
 DEAL_II_NAMESPACE_OPEN
@@ -208,8 +207,13 @@ protected:
    * member variables are marked as 'mutable'.
    *
    * The current class uses essentially the same fields for storage
-   * as the MappingQ1 class. Consequently, it inherits from
-   * MappingQ1::InternalData, rather than from Mapping::InternalDataBase.
+   * as the MappingQGeneric class. Consequently, it inherits from
+   * MappingQGeneric::InternalData, rather than from Mapping::InternalDataBase.
+   * The principal difference to MappingQGeneric::InternalData is that
+   * MappingQ switches between $Q_1$ and $Q_p$ mappings depending
+   * on the cell we are on, so the internal data object needs to
+   * also store a pointer to an InternalData object that pertains
+   * to a $Q_1$ mapping.
    */
   class InternalData : public MappingQGeneric<dim,spacedim>::InternalData
   {
index 459a1542041cee3c18de96dd4e4550905a9c8607..5bc094816e4ed089698559b9d5340079df3d5a4d 100644 (file)
@@ -44,7 +44,9 @@ DEAL_II_NAMESPACE_OPEN
  * edges are not). This is the standard mapping used for polyhedral domains. It
  * is also the mapping used throughout deal.II for many functions that come in
  * two variants, one that allows to pass a mapping argument explicitly and one
- * that simply falls back to the MappingQ1 class declared here.
+ * that simply falls back to the MappingQ1 class declared here. (Or, in fact,
+ * to an object of kind MappingQGeneric(1), which implements exactly the
+ * functionality of this class.)
  *
  * The shape functions for this mapping are the same as for the finite
  * element FE_Q of polynomial degree 1. Therefore, coupling these two
@@ -73,14 +75,27 @@ public:
 
 
 /**
- * In order to avoid creation of static MappingQ1 objects at several places in
- * the library, we define a static MappingQ1 object once and for all, for use
- * in places where a $Q_1$ mapping is required but do not want to create a new
- * object of this type everytime we get there.
+ * Many places in the library by default use (bi-,tri-)linear mappings
+ * unless users explicitly provide a different mapping to use. In these
+ * cases, the called function has to create a $Q_1$ mapping object, i.e.,
+ * an object of kind MappingQGeneric(1). This is costly. It would also be
+ * costly to create such objects as static objects in the affected
+ * functions, because static objects are never destroyed throughout the
+ * lifetime of a program, even though they only have to be created once
+ * the first time code runs through a particular function.
+ *
+ * In order to avoid creation of (static or dynamic) $Q_1$ mapping objects
+ * in these contexts throughout the library, this class defines a static
+ * $Q_1$ mapping object. This object can then be used in all of those
+ * places where such an object is needed.
  */
 template <int dim, int spacedim=dim>
 struct StaticMappingQ1
 {
+  /**
+   * The static $Q_1$ mapping object discussed in the documentation
+   * of this class.
+   */
   static MappingQGeneric<dim, spacedim> mapping;
 };
 
index d02844fb7b49ca9e1f7c113a91f16f09d6331c74..bc46b3a48825887d251ba7fab3a1d77a2b8b1054 100644 (file)
@@ -117,7 +117,8 @@ public:
   unsigned int get_degree () const;
 
   /**
-   * Always returns @p true because MappingQ1 preserves vertex locations.
+   * Always returns @p true because the default implementation of
+   * functions in this class preserves vertex locations.
    */
   virtual
   bool preserves_vertex_locations () const;
@@ -634,7 +635,8 @@ protected:
 
   /**
    * Make MappingQ a friend since it needs to call the
-   * fill_fe_values() functions on its MappingQ1 sub-object.
+   * fill_fe_values() functions on its MappingQGeneric(1)
+   * sub-object.
    */
   template <int, int> friend class MappingQ;
 };
index a4796b1b8daf6843894ea666dedc4d018b1d97f5..9a07b743ea3893793e6a8c0f77c2fc36bd0853da 100644 (file)
@@ -318,11 +318,15 @@ namespace GridOutFlags
     bool color_lines_on_user_flag;
 
     /**
-     * This is the number of points on a boundary face, that are plotted
-     * additionally to the vertices of the face.
+     * The number of points on a boundary face that are plotted
+     * in addition to the vertices of the face.
      *
-     * This is used if the mapping used is not the standard @p MappingQ1
-     * mapping.
+     * This number is only used if the mapping used is not simply
+     * the standard $Q_1$ mapping (i.e., an object of kind
+     * MappingQGeneric(1)) that may describe edges of cells as
+     * curved and that will then be approximated using line
+     * segments with a number of intermediate points as described
+     * by the current variable.
      */
     unsigned int n_boundary_face_points;
 
index 62be03ce01bcbd301554079ce53b5fac9411f07b..33d4d5a6d0425c2f00382f8a9813fb9b413186e9 100644 (file)
@@ -111,15 +111,20 @@ public:
    * support points of the 1D Gauss-Lobatto quadrature formula.
    *
    * The number of points requested is given by the size of the vector @p
-   * points. It is the task of the derived classes to arrange the points in
-   * approximately equal distances.
+   * points. It is the task of derived classes to arrange the points in
+   * approximately equal distances along the length of the line
+   * segment on the boundary bounded by the vertices of the first
+   * argument.
    *
-   * This function is called by the @p MappingQ class. This happens on each
-   * face line of a cells that has got at least one boundary line.
-   *
-   * As this function is not needed for @p MappingQ1, it is not made pure
-   * virtual, to avoid the need to overload it.  The default implementation
-   * throws an error in any case, however.
+   * Among other places in the library, this function is called by
+   * the Mapping classes, for example the @p MappingQGeneric class. On
+   * the other hand, not all mapping classes actually require intermediate
+   * points on lines (for example, $Q_1$ mappings do not). Consequently
+   * this function is not made pure virtual, to allow users to define
+   * their own boundary classes without having to overload this function.
+   * However, the default implementation throws an error in any case and
+   * can, consequently, not be used if you use a mapping that does need
+   * the information provided by this function.
    */
   virtual
   void
@@ -137,13 +142,15 @@ public:
    * to arrange the points such they split the quad into <tt>(m+1)(m+1)</tt>
    * approximately equal-sized subquads.
    *
-   * This function is called by the <tt>MappingQ<3></tt> class. This happens
-   * each face quad of cells in 3d that has got at least one boundary face
-   * quad.
-   *
-   * As this function is not needed for @p MappingQ1, it is not made pure
-   * virtual, to avoid the need to overload it.  The default implementation
-   * throws an error in any case, however.
+   * Among other places in the library, this function is called by
+   * the Mapping classes, for example the @p MappingQGeneric class. On
+   * the other hand, not all mapping classes actually require intermediate
+   * points on quads (for example, $Q_1$ mappings do not). Consequently
+   * this function is not made pure virtual, to allow users to define
+   * their own boundary classes without having to overload this function.
+   * However, the default implementation throws an error in any case and
+   * can, consequently, not be used if you use a mapping that does need
+   * the information provided by this function.
    */
   virtual
   void
index 44bea87e0a2dc2065fe3fe61b2e0356b5b1d83c8..3093d11267998eb6dd575cb1d7a4856840481292 100644 (file)
@@ -28,7 +28,6 @@
 
 DEAL_II_NAMESPACE_OPEN
 
-template <int dim, int spacedim> class MappingQ1;
 template <int dim, int spacedim> class FiniteElement;
 
 
@@ -70,9 +69,9 @@ namespace internal
                     const dealii::hp::QCollection<q_dim>     &q_collection,
                     const UpdateFlags             update_flags);
       /**
-       * Constructor. Set the fields of this class to the values indicated by
-       * the parameters to the constructor, and choose a @p MappingQ1 object
-       * for the mapping object.
+       * Constructor. This constructor is equivalent to the other one except
+       * that it makes the object use a $Q_1$ mapping (i.e., an object of
+       * type MappingQGeneric(1)) implicitly.
        */
       FEValuesBase (const dealii::hp::FECollection<dim,FEValues::space_dimension> &fe_collection,
                     const dealii::hp::QCollection<q_dim> &q_collection,
@@ -240,7 +239,7 @@ namespace hp
      * the signature of this function to make it compatible with the signature
      * of the respective constructor of the usual FEValues object, with the
      * respective parameter in that function also being the return value of
-     * the <tt>DoFHandler::get_fe()</tt> function.
+     * the DoFHandler::get_fe() function.
      */
     FEValues (const dealii::hp::MappingCollection<dim,spacedim> &mapping_collection,
               const dealii::hp::FECollection<dim,spacedim>  &fe_collection,
@@ -249,14 +248,15 @@ namespace hp
 
 
     /**
-     * Constructor. Initialize this object with the given parameters, and
-     * choose a @p MappingQ1 object for the mapping object.
+     * Constructor. This constructor is equivalent to the other one except
+     * that it makes the object use a $Q_1$ mapping (i.e., an object of
+     * type MappingQGeneric(1)) implicitly.
      *
      * The finite element collection parameter is actually ignored, but is in
      * the signature of this function to make it compatible with the signature
      * of the respective constructor of the usual FEValues object, with the
      * respective parameter in that function also being the return value of
-     * the <tt>DoFHandler::get_fe()</tt> function.
+     * the DoFHandler::get_fe() function.
      */
     FEValues (const hp::FECollection<dim,spacedim> &fe_collection,
               const hp::QCollection<dim>      &q_collection,
@@ -304,7 +304,7 @@ namespace hp
      * constructor of this class with index given by
      * <code>cell-@>active_fe_index()</code>, i.e. the same index as that of
      * the finite element. As above, if the mapping collection contains only a
-     * single element (a frequent case if one wants to use a MappingQ1 object
+     * single element (a frequent case if one wants to use a $Q_1$ mapping
      * for all finite elements in an hp discretization), then this single
      * mapping is used unless a different value for this argument is
      * specified.
@@ -385,8 +385,9 @@ namespace hp
 
 
     /**
-     * Constructor. Initialize this object with the given parameters, and
-     * choose a @p MappingQ1 object for the mapping object.
+     * Constructor. This constructor is equivalent to the other one except
+     * that it makes the object use a $Q_1$ mapping (i.e., an object of
+     * type MappingQGeneric(1)) implicitly.
      *
      * The finite element collection parameter is actually ignored, but is in
      * the signature of this function to make it compatible with the signature
@@ -439,7 +440,7 @@ namespace hp
      * constructor of this class with index given by
      * <code>cell-@>active_fe_index()</code>, i.e. the same index as that of
      * the finite element. As above, if the mapping collection contains only a
-     * single element (a frequent case if one wants to use a MappingQ1 object
+     * single element (a frequent case if one wants to use a $Q_1$ mapping
      * for all finite elements in an hp discretization), then this single
      * mapping is used unless a different value for this argument is
      * specified.
@@ -503,8 +504,9 @@ namespace hp
 
 
     /**
-     * Constructor. Initialize this object with the given parameters, and
-     * choose a @p MappingQ1 object for the mapping object.
+     * Constructor. This constructor is equivalent to the other one except
+     * that it makes the object use a $Q_1$ mapping (i.e., an object of
+     * type MappingQGeneric(1)) implicitly.
      *
      * The finite element collection parameter is actually ignored, but is in
      * the signature of this function to make it compatible with the signature
@@ -547,7 +549,7 @@ namespace hp
      * constructor of this class with index given by
      * <code>cell-@>active_fe_index()</code>, i.e. the same index as that of
      * the finite element. As above, if the mapping collection contains only a
-     * single element (a frequent case if one wants to use a MappingQ1 object
+     * single element (a frequent case if one wants to use a $Q_1$ mapping
      * for all finite elements in an hp discretization), then this single
      * mapping is used unless a different value for this argument is
      * specified.
index 10706dbd32ac6d7c48b151e89b59b6e27bf2cee5..c03f82d3095c7e01105f6bb86142536c3d2803a2 100644 (file)
@@ -112,9 +112,19 @@ namespace hp
 
 
   /**
-   * In order to avoid creation of static MappingQ1 objects at several places
-   * in the library, this class defines a static collection of mappings with a
-   * single MappingQ1 mapping object once and for all places where it is
+   * Many places in the library by default use (bi-,tri-)linear mappings
+   * unless users explicitly provide a different mapping to use. In these
+   * cases, the called function has to create a $Q_1$ mapping object, i.e.,
+   * an object of kind MappingQGeneric(1). This is costly. It would also be
+   * costly to create such objects as static objects in the affected
+   * functions, because static objects are never destroyed throughout the
+   * lifetime of a program, even though they only have to be created once
+   * the first time code runs through a particular function.
+   *
+   * In order to avoid creation of (static or dynamic) $Q_1$ mapping objects
+   * in these contexts throughout the library, this class defines a static
+   * collection of mappings with a single $Q_1$ mapping object. This collection
+   * can then be used in all of those places where such a collection is
    * needed.
    */
   template<int dim, int spacedim=dim>
@@ -122,7 +132,7 @@ namespace hp
   {
   public:
     /**
-     * The publicly available static Q1 mapping collection object.
+     * The publicly available static $Q_1$ mapping collection object.
      */
     static MappingCollection<dim,spacedim> mapping_collection;
   };
index 4725235c167b5c2a247dfc1c318701c106b12481..fa52f5e670dc984f9642eb11bbe1e06e838a5fd0 100644 (file)
@@ -1582,8 +1582,10 @@ public:
                 const unsigned int        first_selected_component = 0);
 
   /**
-   * Constructor for the reduced functionality. Similar as the other
-   * constructor but uses MappingQ1 implicitly.
+   * Constructor for the reduced functionality. This constructor is equivalent
+   * to the other one except
+   * that it makes the object use a $Q_1$ mapping (i.e., an object of
+   * type MappingQGeneric(1)) implicitly.
    */
   FEEvaluation (const FiniteElement<dim> &fe,
                 const Quadrature<1>      &quadrature,
index 099d8c0aa0764ae621b6d6c5191ecdb7b3427b35..50e3a77203ef3fc122c23dd5d9d96bc18e375f00 100644 (file)
@@ -69,7 +69,9 @@ namespace internal
                            const UpdateFlags update_flags);
 
       /**
-       * Constructor. Instead of providing a mapping, use MappingQ1.
+       * Constructor. This constructor is equivalent to the other one except
+       * that it makes the object use a $Q_1$ mapping (i.e., an object of
+       * type MappingQGeneric(1)) implicitly.
        */
       MappingDataOnTheFly (const Quadrature<1> &quadrature,
                            const UpdateFlags update_flags);
index 028af5862df12320a84919b6b3c5a63a2a790b9d..aaefa0b95303d3d85edb0420a5814e8362f32046 100644 (file)
@@ -91,12 +91,12 @@ namespace TrilinosWrappers
  *
  * <h3>Conventions for all functions</h3>
  *
- * There exist two versions of each function. One with a Mapping argument and
- * one without. If a code uses a mapping different from MappingQ1 the
- * functions <em>with</em> mapping argument should be used. Code that uses
- * only MappingQ1 may also use the functions <em>without</em> Mapping
- * argument. Each of these latter functions create a MappingQ1 object and just
- * call the respective functions with that object as mapping argument.
+ * There exist two versions of almost all functions, one that takes an
+ * explicit Mapping argument and one that does not. The second one generally
+ * calls the first with an implicit $Q_1$ argument (i.e., with an argument of
+ * kind MappingQGeneric(1)). If your intend your code to use a different
+ * mapping than a (bi-/tri-)linear one, then you need to call the
+ * functions <b>with</b> mapping argument should be used.
  *
  * All functions take a sparse matrix object to hold the matrix to be created.
  * The functions assume that the matrix is initialized with a sparsity pattern
index 7a8fa5fb064bee767540ca51ffef4e683c998fbe..0c893bfdc1e76516f5c27c156670a926f1051dbc 100644 (file)
@@ -59,18 +59,13 @@ class ConstraintMatrix;
  * projections of continuous functions to the finite element space and other
  * operations.
  *
- * @note There exist two versions of almost each function. One with a Mapping
- * argument and one without. If a code uses a mapping different from MappingQ1
- * the functions <b>with</b> mapping argument should be used. Code that uses
- * only MappingQ1 may also use the functions without Mapping argument. Each of
- * these latter functions create a MappingQ1 object and just call the
- * respective functions with that object as mapping argument. The functions
- * without Mapping argument still exist to ensure backward compatibility.
- * Nevertheless it is advised to change the user's codes to store a specific
- * Mapping object and to use the functions that take this Mapping object as
- * argument. This gives the possibility to easily extend the user codes to
- * work also on mappings of higher degree, this just by exchanging MappingQ1
- * by, for example, a MappingQ or another Mapping object of interest.
+ * @note There exist two versions of almost all functions, one that takes an
+ * explicit Mapping argument and one that does not. The second one generally
+ * calls the first with an implicit $Q_1$ argument (i.e., with an argument of
+ * kind MappingQGeneric(1)). If your intend your code to use a different
+ * mapping than a (bi-/tri-)linear one, then you need to call the
+ * functions <b>with</b> mapping argument should be used.
+ *
  *
  * <h3>Description of operations</h3>
  *
@@ -638,7 +633,7 @@ namespace VectorTools
 
   /**
    * Calls the project() function above, with a collection of
-   * MappingQ1@<dim@>() objects.
+   * $Q_1$ mapping objects, i.e., with hp::StaticMappingQ1::mapping_collection.
    */
   template <int dim, class VECTOR, int spacedim>
   void project (const hp::DoFHandler<dim,spacedim>    &dof,
@@ -1386,7 +1381,7 @@ namespace VectorTools
    * @image html no_normal_flux_1.png
    * </p>
    *
-   * Here, we have two cells that use a bilinear mapping (i.e. MappingQ1).
+   * Here, we have two cells that use a bilinear mapping (i.e., MappingQGeneric(1)).
    * Consequently, for each of the cells, the normal vector is perpendicular
    * to the straight edge. If the two edges at the top and right are meant to
    * approximate a curved boundary (as indicated by the dashed line), then

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.