]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Better document FEInterfaceValues::reinit().
authorWolfgang Bangerth <bangerth@colostate.edu>
Thu, 13 Apr 2023 20:53:16 +0000 (14:53 -0600)
committerWolfgang Bangerth <bangerth@colostate.edu>
Thu, 13 Apr 2023 20:53:16 +0000 (14:53 -0600)
include/deal.II/fe/fe_interface_values.h

index 27493ef784be10e5bf800c680d1f317acac7359f..b4489f44be56033ec3dda16524f9c2f449845d12 100644 (file)
@@ -1462,6 +1462,64 @@ public:
    * The arguments (including their order) are identical to the @p face_worker
    * arguments in MeshWorker::mesh_loop().
    *
+   * In order to do integration on a face or sub-face, this object will have to
+   * choose what quadrature formula to use. This is simple if you initialized
+   * the current FEInterfaceValues object with just a single FiniteElement and
+   * a single (face) Quadrature object, because in that case there is only one
+   * element and quadrature that will be used for all interfaces. But it is not
+   * so simple in the hp case where there may be different elements used on
+   * different cells, and different quadrature formulas should be used on
+   * different faces; one may also want to use a different mapping for different
+   * faces. As a consequence, you would have initialized the current object
+   * with a hp::FECollection, hp::QCollection, and possible an
+   * hp::MappingCollection object. The question then is: For a given face or
+   * subface, which quadrature and mapping should be used? The following
+   * decision tree will then be used:
+   * -# If the `q_index` and `mapping_index` arguments to this function are
+   *    explicitly specified (rather than leaving them at their default
+   *    values), then these indices will be used to select which element
+   *    of the hp::QCollection and hp::MappingCollection passed to the
+   *    constructor should serve as the quadrature and mapping to be used.
+   * -# If one of these arguments is left at its default value, then the
+   *    function will need to choose a quadrature and/or mapping that is
+   *    appropriate for the two finite element spaces used on the two cells
+   *    adjacent to the current interface. To this end, we try to find out
+   *    which of the two spaces is "larger" (say, if you had used $Q_2$
+   *    and $Q_4$ elements on the two adjacent cells, then the $Q_4$
+   *    element is the larger one); the determination of which space
+   *    is "larger" is made using the hp::FECollection::find_dominated_fe()
+   *    function, which is not necessarily intended for this kind of query,
+   *    but yields a result that serves just fine for our purposes here.
+   *    We then operate on the assumption that the quadrature object
+   *    associated with the "larger" of the two spaces is the appropriate
+   *    one to use for the face that separates these two spaces.
+   *    - If this function returns that one of the two elements in question
+   *      is dominated by the other, then presumably it is "larger" one and
+   *      we take the quadrature formula and mapping that corresponds
+   *      to this "larger" element is. For example, for the $Q_2$ element
+   *      mentioned above, one would generally use a QGauss(3) quadrature
+   *      formula, whereas for the $Q_4$ element, one would use QGauss(5).
+   *      To integrate jump and average terms on the interface between
+   *      cells using these two elements, QGauss(5) is appropriate. Because,
+   *      typically, people will order elements
+   *      in the hp::FECollection in the same order as the quadrature and
+   *      mapping objects in hp::QCollection and hp::MappingCollection, this
+   *      function will use the index of the "larger" element in the
+   *      hp::FECollection to also index into the hp::QCollection and
+   *      hp::MappingCollection to retrieve quadrature and mapping objects
+   *      appropriate for the current face.
+   *    - There are cases where neither element dominates the other. For
+   * example, if one uses $Q_2\times Q_1$ and $Q_1\times Q_2$ elements on
+   *      neighboring cells, neither of the two spaces dominates the other --
+   *      or, in the context of the current function, neither space is "larger"
+   *      than the other. In that case, there is no way for the current function
+   *      to determine quadrature and mapping objects associated with the two
+   *      elements are the appropriate ones. If that happens, you will get an
+   *      error -- and the only way to avoid the error is to explicitly specify
+   *      for these interfaces which quadrature and mapping objects you want
+   *      to use, by providing non-default values for the @p q_index and
+   *      @p mapping_index arguments to this function.
+   *
    * @param[in] cell An iterator to the first cell adjacent to the interface.
    * @param[in] face_no An integer identifying which face of the first cell the
    *   interface is on.
@@ -1479,21 +1537,19 @@ public:
    *   cell.
    * @param[in] sub_face_no_neighbor Like `sub_face_no`, just for the
    *   neighboring cell.
-   * @param[in] q_index If left at its default, use the quadrature formula
-   * within the hp::QCollection passed to the constructor as given by the
-   * dominating finite element across the interface (only used if the
-   * FEInterface object is initialized with an hp::FECollection, an
-   * hp::QCollection, and possibly an hp::MappingCollection).
-   * @param[in] mapping_index If left at its default, use the mapping within the
-   * hp::MappingCollection passed to the constructor as given by the dominating
-   * finite element across the interface (only used if the FEInterface object
-   * is initialized with an hp::FECollection, an hp::QCollection, and possibly
-   * an hp::MappingCollection).
+   * @param[in] q_index The index of the quadrature object within the
+   *   hp::QCollection passed to the constructor to use on the current
+   *   interface. See the documentation above what happens if this argument
+   *   is not explicitly provided but left at its default value.
+   * @param[in] mapping_index The index of the mapping object within the
+   *   hp::MappingCollection passed to the constructor to use on the current
+   *   interface. See the documentation above what happens if this argument
+   *   is not explicitly provided but left at its default value.
    * @param[in] fe_index If left at its default, use the finite element within
-   * the hp::FECollection passed to the constructor as given by the dominating
-   * finite element across the interface (only used if the FEInterface object
-   * is initialized with an hp::FECollection, an hp::QCollection, and possibly
-   * an hp::MappingCollection).
+   *   the hp::FECollection passed to the constructor as given by the dominating
+   *   finite element across the interface (only used if the FEInterface object
+   *   is initialized with an hp::FECollection, an hp::QCollection, and possibly
+   *   an hp::MappingCollection).
    */
   template <class CellIteratorType, class CellNeighborIteratorType>
   void

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.