From: Marc Fehling <marc.fehling@gmx.net>
Date: Wed, 22 Aug 2018 21:41:32 +0000 (-0600)
Subject: Extend doc on 'compute_line_dof_identities' and 'get_active_neighbors'.
X-Git-Tag: v9.1.0-rc1~763^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9ccb203eb8409ad2d91c5991a18fd22c94ea1067;p=dealii.git

Extend doc on 'compute_line_dof_identities' and 'get_active_neighbors'.
---

diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index 44adc18cc7..09a6f8f74a 100644
--- a/include/deal.II/grid/grid_tools.h
+++ b/include/deal.II/grid/grid_tools.h
@@ -1232,7 +1232,14 @@ namespace GridTools
 
   /**
    * Extract the active cells around a given cell @p cell and return them in
-   * the vector @p active_neighbors.
+   * the vector @p active_neighbors. These neighbors are specifically the
+   * <i>face</i> neighbors of a cell or, if that neighbor is further
+   * refined, its active children that border on that face. On the other
+   * hand, the neighbors returned do not include cells that lie, for
+   * example, diagonally opposite to a vertex but are not face neighbors
+   * themselves. (In 3d, it also does not include cells that are
+   * adjacent to one of the edges of the current cell, but are not
+   * face neighbors.)
    *
    * @tparam MeshType A type that satisfies the requirements of the
    * @ref ConceptMeshType "MeshType concept".
diff --git a/source/dofs/dof_handler_policy.cc b/source/dofs/dof_handler_policy.cc
index 71e6e5408e..89f6b0d5ea 100644
--- a/source/dofs/dof_handler_policy.cc
+++ b/source/dofs/dof_handler_policy.cc
@@ -872,6 +872,22 @@ namespace internal
                                            fe_index_2 =
                                              line->nth_active_fe_index(g);
 
+                        // as described in the hp paper, we only unify on lines
+                        // when there are at most two different FE objects
+                        // assigned on it.
+                        // however, more than two 'active_fe_indices' can be
+                        // attached that still fulfill the above criterion,
+                        // i.e. when two different FiniteElement objects are
+                        // assigned to neighboring cells that map their degrees
+                        // of freedom one-to-one.
+                        // we cannot verify with certainty if two dofs each of
+                        // separate FiniteElement objects actually map
+                        // one-to-one. however, checking for the number of
+                        // 'dofs_per_line' turned out to be a reasonable
+                        // approach, that also works for e.g. two different
+                        // FE_Q objects of the same order, from which one is
+                        // enhanced by a bubble function that is zero on the
+                        // boundary.
                         if ((dof_handler.get_fe(fe_index_1).dofs_per_line ==
                              dof_handler.get_fe(fe_index_2).dofs_per_line) &&
                             (dof_handler.get_fe(fe_index_1).dofs_per_line > 0))