]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Document Mapping::InternalDataBase better.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Sun, 26 Jul 2015 17:23:26 +0000 (12:23 -0500)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Sun, 26 Jul 2015 18:17:42 +0000 (13:17 -0500)
include/deal.II/fe/mapping.h

index 0e2776ce3ed8bffa30f9867f55edfdc1f3e7efd3..226975c8ca1286f432256180b2b707b94e166d3a 100644 (file)
@@ -264,20 +264,77 @@ public:
     const Point<spacedim>                            &p) const = 0;
 
   /**
-   * Base class for internal data of finite element and mapping objects. The
-   * internal mechanism is that upon construction of a @p FEValues objects, it
+   * Base class for internal data of mapping objects. The
+   * internal mechanism is that upon construction of a FEValues object, it
    * asks the mapping and finite element classes that are to be used to
    * allocate memory for their own purpose in which they may store data that
    * only needs to be computed once. For example, most finite elements will
    * store the values of the shape functions at the quadrature points in this
    * object, since they do not change from cell to cell and only need to be
-   * computed once. Since different @p FEValues objects using different
-   * quadrature rules might access the same finite element object at the same
-   * time, it is necessary to create one such object per @p FEValues object.
-   * Ownership of this object is then transferred to the @p FEValues object,
-   * but a pointer to this object is passed to the finite element object every
-   * time it shall compute some data so that it has access to the precomputed
-   * values stored there.
+   * computed once. The same may be true for Mapping classes that want to
+   * only evaluate the shape functions used for mapping once at the quadrature
+   * points.
+   *
+   * Since different FEValues objects using different
+   * quadrature rules might access the same mapping object at the same
+   * time, it is necessary to create one such object per FEValues object.
+   * FEValues does this by calling Mapping::get_data(), or in reality the
+   * implementation of the corresponding function in derived classes.
+   * Ownership of the object created by Mapping::get_data() is then transferred
+   * to the FEValues object,
+   * but a reference to this object is passed to the mapping object every
+   * time it it is asked to compute information on a concrete cell. This
+   * happens when FEValues::reinit() (or the corresponding classes in
+   * FEFaceValues and FESubfaceValues) call Mapping::fill_fe_values()
+   * (and similarly via Mapping::fill_fe_face_values() and
+   * Mapping::fill_fe_subface_values()).
+   *
+   * The purpose of this class is for mapping objects to store information
+   * that can be computed once at the beginning, on the reference cell,
+   * and to access it later when computing information on a concrete cell.
+   * As such, the object handed to Mapping::fill_fe_values() is marked as
+   * <code>const</code>, because the assumption is that at the time this
+   * information is used, it will not need to modified again. However,
+   * classes derived from Mapping can also use such objects for two other
+   * purposes:
+   *
+   * - To provide scratch space for computations that are done in
+   *   Mapping::fill_fe_values() and similar functions. Some of the
+   *   derived classes would like to use scratch arrays and it would
+   *   be a waste of time to allocate these arrays every time this
+   *   function is called, just to de-allocate it again at the end
+   *   of the function. Rather, one could allocate this memory once
+   *   as a member variable of the current class, and simply use
+   *   it in Mapping::fill_fe_values().
+   * - After calling Mapping::fill_fe_values(), FEValues::reinit()
+   *   calls FiniteElement::fill_fe_values() where the finite element
+   *   computes values, gradients, etc of the shape functions using
+   *   both information computed once at the beginning using a mechanism
+   *   similar to the one described here (see FiniteElement::InternalDataBase)
+   *   as well as the data already computed by Mapping::fill_fe_values().
+   *   As part of its work, some implementations of
+   *   FiniteElement::fill_fe_values() need to transform shape function
+   *   data, and they do so by calling Mapping::transform(). The call
+   *   to the latter function also receives a reference to the
+   *   Mapping::InternalDataBase object. Since Mapping::transform()
+   *   may be called many times on each cell, it is sometimes worth
+   *   for derived classes to compute some information only once
+   *   in Mapping::fill_fe_values() and reuse it in
+   *   Mapping::transform(). This information can also be stored in
+   *   the classes that derived mapping classes derive from
+   *   InternalDataBase.
+   *
+   * In both of these cases, the InternalDataBase object being passed
+   * around is "morally const", i.e., no external observer can tell
+   * whether a scratch array or some intermediate data for
+   * Mapping::transform() is being modified by Mapping::fill_fe_values()
+   * or not. Consequently, the InternalDataBase objects are always
+   * passed around as <code>const</code> objects. Derived classes
+   * that would like to make use of the two additional uses outlined
+   * above therefore need to mark the member variables they want to
+   * use for these purposes as <code>mutable</code> to allow for their
+   * modification despite the fact that the surrounding object is
+   * marked as <code>const</code>.
    */
   class InternalDataBase: public Subscriptor
   {
@@ -289,7 +346,7 @@ public:
 
   public:
     /**
-     * Constructor. Sets @p UpdateFlags to @p update_default and @p first_cell
+     * Constructor. Sets update_flags to @p update_default and @p first_cell
      * to @p true.
      */
     InternalDataBase ();
@@ -366,7 +423,6 @@ public:
      */
     std::vector<Tensor<2,spacedim> > support_point_inverse_gradients;
 
-
   private:
     /**
      * The value returned by @p is_first_cell.
@@ -374,6 +430,7 @@ public:
     bool first_cell;
   };
 
+
   /**
    * Transform a field of vectors or 1-differential forms according to the
    * selected MappingType.
@@ -457,7 +514,6 @@ public:
    * 1@></code> with a <code>Tensor@<1,dim@></code> when using
    * mapping_covariant() in the function transform above this one.
    */
-
   virtual
   void
   transform (const VectorSlice<const std::vector< DerivativeForm<1, dim, spacedim> > > input,

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.