* 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.
* 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
projects / dealii.git / commitdiff