From 8cf4083725595ed71933d17766db588b73b551e5 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 7 Oct 2015 14:46:47 -0500 Subject: [PATCH] Remove mention of MappingQ1 from the documentation. In preparation to possibly deprecating MappingQ1 in favor of MappingQGeneric(1), remove all mentions of MappingQ1 from the documentation. --- include/deal.II/fe/fe_values.h | 12 ++++-- include/deal.II/fe/mapping.h | 4 +- include/deal.II/fe/mapping_q.h | 10 +++-- include/deal.II/fe/mapping_q1.h | 25 ++++++++++--- include/deal.II/fe/mapping_q_generic.h | 6 ++- include/deal.II/grid/grid_out.h | 12 ++++-- include/deal.II/grid/tria_boundary.h | 37 +++++++++++-------- include/deal.II/hp/fe_values.h | 32 ++++++++-------- include/deal.II/hp/mapping_collection.h | 18 +++++++-- include/deal.II/matrix_free/fe_evaluation.h | 6 ++- .../matrix_free/mapping_data_on_the_fly.h | 4 +- include/deal.II/numerics/matrix_tools.h | 12 +++--- include/deal.II/numerics/vector_tools.h | 23 +++++------- 13 files changed, 125 insertions(+), 76 deletions(-) diff --git a/include/deal.II/fe/fe_values.h b/include/deal.II/fe/fe_values.h index 62a7fa76a8..6aa1583170 100644 --- a/include/deal.II/fe/fe_values.h +++ b/include/deal.II/fe/fe_values.h @@ -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 &fe, const Quadrature &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 &fe, const Quadrature &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 &fe, const Quadrature &face_quadrature, diff --git a/include/deal.II/fe/mapping.h b/include/deal.II/fe/mapping.h index 3a99fbc542..5e236ffd41 100644 --- a/include/deal.II/fe/mapping.h +++ b/include/deal.II/fe/mapping.h @@ -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; diff --git a/include/deal.II/fe/mapping_q.h b/include/deal.II/fe/mapping_q.h index 8c44597f28..86447fc6fe 100644 --- a/include/deal.II/fe/mapping_q.h +++ b/include/deal.II/fe/mapping_q.h @@ -18,7 +18,6 @@ #include -#include #include 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::InternalData { diff --git a/include/deal.II/fe/mapping_q1.h b/include/deal.II/fe/mapping_q1.h index 459a154204..5bc094816e 100644 --- a/include/deal.II/fe/mapping_q1.h +++ b/include/deal.II/fe/mapping_q1.h @@ -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 struct StaticMappingQ1 { + /** + * The static $Q_1$ mapping object discussed in the documentation + * of this class. + */ static MappingQGeneric mapping; }; diff --git a/include/deal.II/fe/mapping_q_generic.h b/include/deal.II/fe/mapping_q_generic.h index d02844fb7b..bc46b3a488 100644 --- a/include/deal.II/fe/mapping_q_generic.h +++ b/include/deal.II/fe/mapping_q_generic.h @@ -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 friend class MappingQ; }; diff --git a/include/deal.II/grid/grid_out.h b/include/deal.II/grid/grid_out.h index a4796b1b8d..9a07b743ea 100644 --- a/include/deal.II/grid/grid_out.h +++ b/include/deal.II/grid/grid_out.h @@ -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; diff --git a/include/deal.II/grid/tria_boundary.h b/include/deal.II/grid/tria_boundary.h index 62be03ce01..33d4d5a6d0 100644 --- a/include/deal.II/grid/tria_boundary.h +++ b/include/deal.II/grid/tria_boundary.h @@ -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 (m+1)(m+1) * approximately equal-sized subquads. * - * This function is called by the MappingQ<3> 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 diff --git a/include/deal.II/hp/fe_values.h b/include/deal.II/hp/fe_values.h index 44bea87e0a..3093d11267 100644 --- a/include/deal.II/hp/fe_values.h +++ b/include/deal.II/hp/fe_values.h @@ -28,7 +28,6 @@ DEAL_II_NAMESPACE_OPEN -template class MappingQ1; template class FiniteElement; @@ -70,9 +69,9 @@ namespace internal const dealii::hp::QCollection &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 &fe_collection, const dealii::hp::QCollection &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 DoFHandler::get_fe() function. + * the DoFHandler::get_fe() function. */ FEValues (const dealii::hp::MappingCollection &mapping_collection, const dealii::hp::FECollection &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 DoFHandler::get_fe() function. + * the DoFHandler::get_fe() function. */ FEValues (const hp::FECollection &fe_collection, const hp::QCollection &q_collection, @@ -304,7 +304,7 @@ namespace hp * constructor of this class with index given by * cell-@>active_fe_index(), 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 * cell-@>active_fe_index(), 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 * cell-@>active_fe_index(), 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. diff --git a/include/deal.II/hp/mapping_collection.h b/include/deal.II/hp/mapping_collection.h index 10706dbd32..c03f82d309 100644 --- a/include/deal.II/hp/mapping_collection.h +++ b/include/deal.II/hp/mapping_collection.h @@ -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 @@ -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 mapping_collection; }; diff --git a/include/deal.II/matrix_free/fe_evaluation.h b/include/deal.II/matrix_free/fe_evaluation.h index 4725235c16..fa52f5e670 100644 --- a/include/deal.II/matrix_free/fe_evaluation.h +++ b/include/deal.II/matrix_free/fe_evaluation.h @@ -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 &fe, const Quadrature<1> &quadrature, diff --git a/include/deal.II/matrix_free/mapping_data_on_the_fly.h b/include/deal.II/matrix_free/mapping_data_on_the_fly.h index 099d8c0aa0..50e3a77203 100644 --- a/include/deal.II/matrix_free/mapping_data_on_the_fly.h +++ b/include/deal.II/matrix_free/mapping_data_on_the_fly.h @@ -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); diff --git a/include/deal.II/numerics/matrix_tools.h b/include/deal.II/numerics/matrix_tools.h index 028af5862d..aaefa0b953 100644 --- a/include/deal.II/numerics/matrix_tools.h +++ b/include/deal.II/numerics/matrix_tools.h @@ -91,12 +91,12 @@ namespace TrilinosWrappers * *

Conventions for all functions

* - * 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 with 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. + * 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 with 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 diff --git a/include/deal.II/numerics/vector_tools.h b/include/deal.II/numerics/vector_tools.h index 7a8fa5fb06..0c893bfdc1 100644 --- a/include/deal.II/numerics/vector_tools.h +++ b/include/deal.II/numerics/vector_tools.h @@ -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 with 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 with mapping argument should be used. + * * *

Description of operations

* @@ -638,7 +633,7 @@ namespace VectorTools /** * Calls the project() function above, with a collection of - * MappingQ1@() objects. + * $Q_1$ mapping objects, i.e., with hp::StaticMappingQ1::mapping_collection. */ template void project (const hp::DoFHandler &dof, @@ -1386,7 +1381,7 @@ namespace VectorTools * @image html no_normal_flux_1.png *

* - * 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 -- 2.39.5