From 311f88c92e9e0575a6f431e8412440d8696736a9 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Fri, 5 Oct 2018 18:07:37 -0600 Subject: [PATCH] Update the documentation of FECollection::find_last...(). --- include/deal.II/hp/fe_collection.h | 39 +++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/include/deal.II/hp/fe_collection.h b/include/deal.II/hp/fe_collection.h index f43dcda4b1..15a41dde80 100644 --- a/include/deal.II/hp/fe_collection.h +++ b/include/deal.II/hp/fe_collection.h @@ -246,12 +246,27 @@ namespace hp /** * Try to find a least dominant finite element inside this FECollection * which dominates all of those finite elements in the current collection - * indexed by the numbers provided through @p fes . For example, if + * indexed by the numbers provided through @p fes . In other words, we + * first form the set of elements in this collection that dominate + * all of the ones that are indexed by the argument @p fes, and then + * within that set of dominating elements, we find the least + * dominant one. + * + * For example, if * an FECollection consists of `{FE_Q(1),FE_Q(2),FE_Q(3),FE_Q(4)}` elements - * and we are looking for the least dominant finite element among the - * last two elements of this collection (i.e., @p fes is `{2,3}`), then - * the answer is FE_Q(3) and therefore this function will return its index - * in the FECollection, namely `2`. + * and the argument @p fes equals `{2,3}`, then the set of dominating + * elements consists of `{0,1,2}`, of which `2` (i.e., the `FE_Q(3)`) is the + * least dominant one, and then that's what the function returns. + * + * On the other hand, if the + * FECollection consists of + * `{FE_Q(1)xFE_Q(1),FE_Q(2)xFE_Q(2),FE_Q(2)xFE_Q(3), FE_Q(3)xFE_Q(2)}` + * elements and the argument is again + * @p fes equal to `{2,3}`, then the set of dominating + * elements consists of `{0,1}` because now neither of the last two + * elements dominates the other, of which `1` (i.e., the `FE_Q(2)xFE_Q(2)`) + * is the least dominant one -- so that's what the function returns in + * this case. * * For the purpose of this function by domination we consider either * FiniteElementDomination::Domination::this_element_dominates or @@ -260,16 +275,18 @@ namespace hp * contains `{FE_Q(1),FE_Q(2),FE_Q(3),FE_Q(4)}` and @p fes only has * a single element `{3}`, then the function returns 3. * - * If the function is not able to find a finite element, the function - * returns numbers::invalid_unsigned_int . - * - * Note that for the cases like when FECollection consists of `{FE_Nothing + * If the function is not able to find a finite element that satisfies + * the description above, the function + * returns numbers::invalid_unsigned_int . An example would go like this: + * If the FECollection consists of `{FE_Nothing * x FE_Nothing, FE_Q(1)xFE_Q(2), FE_Q(2)xFE_Q(1)}` with @p fes as `{1}`, * the function will not find a most dominating element as the default * behavior of FE_Nothing is to return * FiniteElementDomination::no_requirements when comparing for face - * domination with any other element. This, therefore, can't be considered - * as a dominating element in the sense described above. + * domination with any other element. In other words, the set of + * dominating elements is empty, and we can not find a least dominant + * one among it. The return value is therefore + * numbers::invalid_unsigned_int. */ unsigned int find_least_face_dominating_fe(const std::set &fes) const; -- 2.39.5