From: Wolfgang Bangerth Date: Thu, 13 Apr 2023 20:53:16 +0000 (-0600) Subject: Better document FEInterfaceValues::reinit(). X-Git-Tag: v9.5.0-rc1~331^2~1 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3b8cb13b3ba05ede976ae72275029eea2ec7e389;p=dealii.git Better document FEInterfaceValues::reinit(). --- diff --git a/include/deal.II/fe/fe_interface_values.h b/include/deal.II/fe/fe_interface_values.h index 27493ef784..b4489f44be 100644 --- a/include/deal.II/fe/fe_interface_values.h +++ b/include/deal.II/fe/fe_interface_values.h @@ -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 void