In preparation to possibly deprecating MappingQ1 in favor of MappingQGeneric(1),
remove all mentions of MappingQ1 from the documentation.
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,
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,
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,
* 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;
#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
* 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
{
* 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
/**
- * 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;
};
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;
/**
* 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;
};
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;
* 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
* 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
DEAL_II_NAMESPACE_OPEN
-template <int dim, int spacedim> class MappingQ1;
template <int dim, int spacedim> class FiniteElement;
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,
* 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,
/**
- * 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,
* 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.
/**
- * 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
* 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.
/**
- * 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
* 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.
/**
- * 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>
{
public:
/**
- * The publicly available static Q1 mapping collection object.
+ * The publicly available static $Q_1$ mapping collection object.
*/
static MappingCollection<dim,spacedim> mapping_collection;
};
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,
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);
*
* <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
* 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>
*
/**
* 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,
* @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