]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Document FiniteElement::get_*_data(). 1863/head
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 11 Nov 2015 21:23:13 +0000 (15:23 -0600)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 11 Nov 2015 21:23:13 +0000 (15:23 -0600)
include/deal.II/fe/fe.h

index 4fd17ef699a917b3d322da14de3ce441897651c1..7cd398fea23e9c7c5f05dd819668ae89236df9ef 100644 (file)
@@ -2193,14 +2193,81 @@ protected:
   requires_update_flags (const UpdateFlags update_flags) const = 0;
 
   /**
-   * Prepare internal data structures and fill in values independent of the
-   * cell. Return a pointer to an object of which the caller of this function
-   * then has to assume ownership (which includes destruction when it is no
-   * more needed).
+   * Create an internal data object and return a pointer to it of which the
+   * caller of this function then assumes ownership. This object will
+   * then be passed to the FiniteElement::fill_fe_values() every time
+   * the finite element shape functions and their derivatives are evaluated
+   * on a concrete cell. The object created here is therefore used by
+   * derived classes as a place for scratch objects that are used in
+   * evaluating shape functions, as well as to store information that
+   * can be pre-computed once and re-used on every cell (e.g., for
+   * evaluating the values and gradients of shape functions on the
+   * reference cell, for later re-use when transforming these values to
+   * a concrete cell).
+   *
+   * This function is the first one called in the process of initializing
+   * a FEValues object for a given mapping and finite element object. The
+   * returned object will later be passed to FiniteElement::fill_fe_values()
+   * for a concrete cell, which will itself place its output into an object
+   * of type internal::FEValues::FiniteElementRelatedData. Since there may
+   * be data that can already be computed in its <i>final</i> form on the
+   * reference cell, this function also receives a reference to the
+   * internal::FEValues::FiniteElementRelatedData object as its last argument.
+   * This output argument is guaranteed to always be the same one when used
+   * with the InternalDataBase object returned by this function. In other
+   * words, the subdivision of scratch data and final data in the returned
+   * object and the @p output_data object is as follows: If data can be
+   * pre-computed on the reference cell in the exact form in which it
+   * will later be needed on a concrete cell, then this function should
+   * already emplace it in the @p output_data object. An example are the
+   * values of shape functions at quadrature points for the usual
+   * Lagrange elements which on a concrete cell are identical to the
+   * ones on the reference cell. On the other hand, if some data can
+   * be pre-computed to make computations on a concrete cell <i>cheaper</i>,
+   * then it should be put into the returned object for later re-use
+   * in a derive class's implementation of FiniteElement::fill_fe_values().
+   * An example are the gradients of shape functions on the reference
+   * cell for Lagrange elements: to compute the gradients of the shape
+   * functions on a concrete cell, one has to multiply the gradients on
+   * the reference cell by the inverse of the Jacobian of the mapping;
+   * consequently, we cannot already compute the gradients on a concrete
+   * cell at the time the current function is called, but we can at least
+   * pre-compute the gradients on the reference cell, and store it
+   * in the object returned.
    *
    * An extensive discussion of the interaction between this function and
    * FEValues can be found in the @ref FE_vs_Mapping_vs_FEValues documentation
-   * module.
+   * module. See also the documentation of the InternalDataBase class.
+   *
+   * @param[in] update_flags A set of UpdateFlags values that describe
+   *   what kind of information the FEValues object requests the finite
+   *   element to compute. This set of flags may also include information
+   *   that the finite element can not compute, e.g., flags that pertain
+   *   to data produced by the mapping. An implementation of this function
+   *   needs to set up all data fields in the returned object that are
+   *   necessary to produce the finite-element related data specified by
+   *   these flags, and may already pre-compute part of this information
+   *   as discussed above. Elements may want to store these update flags
+   *   (or a subset of these flags) in InternalDataBase::update_each so
+   *   they know at the time when FinitElement::fill_fe_values() is called
+   *   what they are supposed to compute
+   * @param[in] mapping A reference to the mapping used for computing
+   *   values and derivatives of shape functions.
+   * @param[in] quadrature A reference to the object that describes where
+   *   the shape functions should be evaluated.
+   * @param[out] output_data A reference to the object that FEValues
+   *   will use in conjunction with the object returned here and where
+   *   an implementation of FiniteElement::fill_fe_values() will place
+   *   the requested information. This allows the current function
+   *   to already pre-compute pieces of information that can be computed
+   *   on the reference cell, as discussed above. FEValues guarantees
+   *   that this output object and the object returned by the current
+   *   function will always be used together.
+   * @return A pointer to an object of a type derived from InternalDataBase
+   *   and that derived classes can use to store scratch data that can
+   *   be pre-computed, or for scratch arrays that then only need to
+   *   be allocated once. The calling site assumes ownership of this
+   *   object and will delete it when it is no longer necessary.
    */
   virtual
   InternalDataBase *
@@ -2210,19 +2277,46 @@ protected:
             dealii::internal::FEValues::FiniteElementRelatedData<dim, spacedim> &output_data) const = 0;
 
   /**
-   * Prepare internal data structure for transformation of faces and fill in
-   * values independent of the cell. Return a pointer to an object of which
-   * the caller of this function then has to assume ownership (which includes
-   * destruction when it is no more needed).
+   * Like get_data(), but return an object that will later be used for
+   * evaluating shape function information at quadrature points on faces
+   * of cells. The object will then be used in calls to implementations of
+   * FiniteElement::fill_fe_face_values(). See the documentation of get_data()
+   * for more information.
    *
    * The default implementation of this function converts the face quadrature
    * into a cell quadrature with appropriate quadrature point locations,
    * and with that calls the get_data() function above that has to be
    * implemented in derived classes.
    *
-   * An extensive discussion of the interaction between this function and
-   * FEValues can be found in the @ref FE_vs_Mapping_vs_FEValues documentation
-   * module.
+   * @param[in] update_flags A set of UpdateFlags values that describe
+   *   what kind of information the FEValues object requests the finite
+   *   element to compute. This set of flags may also include information
+   *   that the finite element can not compute, e.g., flags that pertain
+   *   to data produced by the mapping. An implementation of this function
+   *   needs to set up all data fields in the returned object that are
+   *   necessary to produce the finite-element related data specified by
+   *   these flags, and may already pre-compute part of this information
+   *   as discussed above. Elements may want to store these update flags
+   *   (or a subset of these flags) in InternalDataBase::update_each so
+   *   they know at the time when FinitElement::fill_fe_face_values() is called
+   *   what they are supposed to compute
+   * @param[in] mapping A reference to the mapping used for computing
+   *   values and derivatives of shape functions.
+   * @param[in] quadrature A reference to the object that describes where
+   *   the shape functions should be evaluated.
+   * @param[out] output_data A reference to the object that FEValues
+   *   will use in conjunction with the object returned here and where
+   *   an implementation of FiniteElement::fill_fe_face_values() will place
+   *   the requested information. This allows the current function
+   *   to already pre-compute pieces of information that can be computed
+   *   on the reference cell, as discussed above. FEValues guarantees
+   *   that this output object and the object returned by the current
+   *   function will always be used together.
+   * @return A pointer to an object of a type derived from InternalDataBase
+   *   and that derived classes can use to store scratch data that can
+   *   be pre-computed, or for scratch arrays that then only need to
+   *   be allocated once. The calling site assumes ownership of this
+   *   object and will delete it when it is no longer necessary.
    */
   virtual
   InternalDataBase *
@@ -2232,19 +2326,46 @@ protected:
                  dealii::internal::FEValues::FiniteElementRelatedData<dim, spacedim> &output_data) const;
 
   /**
-   * Prepare internal data structure for transformation of children of faces
-   * and fill in values independent of the cell. Return a pointer to an
-   * object of which the caller of this function then has to assume ownership
-   * (which includes destruction when it is no more needed).
+   * Like get_data(), but return an object that will later be used for
+   * evaluating shape function information at quadrature points on children
+   * of faces of cells. The object will then be used in calls to
+   * implementations of FiniteElement::fill_fe_subface_values(). See the
+   * documentation of get_data() for more information.
    *
    * The default implementation of this function converts the face quadrature
    * into a cell quadrature with appropriate quadrature point locations,
    * and with that calls the get_data() function above that has to be
    * implemented in derived classes.
    *
-   * An extensive discussion of the interaction between this function and
-   * FEValues can be found in the @ref FE_vs_Mapping_vs_FEValues documentation
-   * module.
+   * @param[in] update_flags A set of UpdateFlags values that describe
+   *   what kind of information the FEValues object requests the finite
+   *   element to compute. This set of flags may also include information
+   *   that the finite element can not compute, e.g., flags that pertain
+   *   to data produced by the mapping. An implementation of this function
+   *   needs to set up all data fields in the returned object that are
+   *   necessary to produce the finite-element related data specified by
+   *   these flags, and may already pre-compute part of this information
+   *   as discussed above. Elements may want to store these update flags
+   *   (or a subset of these flags) in InternalDataBase::update_each so
+   *   they know at the time when FinitElement::fill_fe_subface_values()
+   *   is called what they are supposed to compute
+   * @param[in] mapping A reference to the mapping used for computing
+   *   values and derivatives of shape functions.
+   * @param[in] quadrature A reference to the object that describes where
+   *   the shape functions should be evaluated.
+   * @param[out] output_data A reference to the object that FEValues
+   *   will use in conjunction with the object returned here and where
+   *   an implementation of FiniteElement::fill_fe_subface_values() will place
+   *   the requested information. This allows the current function
+   *   to already pre-compute pieces of information that can be computed
+   *   on the reference cell, as discussed above. FEValues guarantees
+   *   that this output object and the object returned by the current
+   *   function will always be used together.
+   * @return A pointer to an object of a type derived from InternalDataBase
+   *   and that derived classes can use to store scratch data that can
+   *   be pre-computed, or for scratch arrays that then only need to
+   *   be allocated once. The calling site assumes ownership of this
+   *   object and will delete it when it is no longer necessary.
    */
   virtual
   InternalDataBase *

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.