Feature: element_face_get_ancestor_face function

src/t8_schemes/t8_default/t8_default_hex/t8_default_hex.hxx

@@ -339,6 +339,24 @@ class t8_default_scheme_hex: public t8_default_scheme_common<t8_default_scheme_h
   int
   element_face_get_parent_face (const t8_element_t *elem, int face) const;
 
+  /** Given an element and a face of an element as well as an ancestor of the element
+   * that has a face that is an ancestor of the given face, compute the corresponding face number of the ancestor element.
+   * 
+   * \param [in] tree_class    The eclass of the current tree.
+   * \param [in]  elem    An element.
+   * \param [in]  face    Then number of a face of \a element.
+   * \param [in]  ancestor An ancestor of \a element that has a common face with \a face. (Could be \a element itself).
+   * \return              The face number \a f_a corresponding to the face of with \a face is a asubface.
+   *                      <0 on failure.
+   */
+  inline int
+  element_face_get_ancestor_face (const t8_element_t *elem, const int face, const t8_element_t *ancestor) const
+  {
+    // For Hex elements the face number does not change when refining.
+    T8_ASSERT (is_ancestor (ancestor, elem));
+    return face;
+  }
+
   /** Given an element and a face of this element. If the face lies on the
    *  tree boundary, return the face number of the tree face.
    *  If not the return value is arbitrary.

src/t8_schemes/t8_default/t8_default_line/t8_default_line.hxx

@@ -352,6 +352,27 @@ class t8_default_scheme_line: public t8_default_scheme_common<t8_default_scheme_
   int
   element_face_get_parent_face (const t8_element_t *elem, int face) const;
 
+  /** Given an element and a face of an element as well as an ancestor of the element
+   * that has a face that is an ancestor of the given face, compute the corresponding face number of the ancestor element.
+   * 
+   * \param [in] tree_class    The eclass of the current tree.
+   * \param [in]  elem    An element.
+   * \param [in]  face    Then number of a face of \a element.
+   * \param [in]  ancestor An ancestor of \a element that has a common face with \a face. (Could be \a element itself).
+   * \return              The face number \a f_a corresponding to the face of with \a face is a asubface.
+   *                      <0 on failure.
+   */
+  inline int
+  element_face_get_ancestor_face (const t8_element_t *elem, const int face, const t8_element_t *ancestor) const
+  {
+    // For Line elements the face number does not change when refining.
+    T8_ASSERT (element_is_valid (elem));
+    T8_ASSERT (element_is_valid (ancestor));
+    T8_ASSERT (0 <= face && face < element_get_num_face (elem));
+    T8_ASSERT (is_ancestor (ancestor, elem));
+    return face;
+  }
+
   /** Given an element and a face of this element. If the face lies on the
    *  tree boundary, return the face number of the tree face.
    *  If not the return value is arbitrary.

src/t8_schemes/t8_default/t8_default_prism/t8_default_prism.hxx

@@ -331,6 +331,27 @@ class t8_default_scheme_prism: public t8_default_scheme_common<t8_default_scheme
   int
   element_face_get_parent_face (const t8_element_t *elem, int face) const;
 
+  /** Given an element and a face of an element as well as an ancestor of the element
+   * that has a face that is an ancestor of the given face, compute the corresponding face number of the ancestor element.
+   * 
+   * \param [in] tree_class    The eclass of the current tree.
+   * \param [in]  elem    An element.
+   * \param [in]  face    Then number of a face of \a element.
+   * \param [in]  ancestor An ancestor of \a element that has a common face with \a face. (Could be \a element itself).
+   * \return              The face number \a f_a corresponding to the face of with \a face is a asubface.
+   *                      <0 on failure.
+   */
+  inline int
+  element_face_get_ancestor_face (const t8_element_t *elem, const int face, const t8_element_t *ancestor) const
+  {
+    // For Prism elements the face number does not change when refining.
+    T8_ASSERT (element_is_valid (elem));
+    T8_ASSERT (element_is_valid (ancestor));
+    T8_ASSERT (0 <= face && face < element_get_num_face (elem));
+    T8_ASSERT (is_ancestor (ancestor, elem));
+    return face;
+  }
+
   /** Given an element and a face of this element. If the face lies on the
    *  tree boundary, return the face number of the tree face.
    *  If not the return value is arbitrary.

src/t8_schemes/t8_default/t8_default_quad/t8_default_quad.hxx

@@ -375,6 +375,27 @@ class t8_default_scheme_quad: public t8_default_scheme_common<t8_default_scheme_
   int
   element_face_get_parent_face (const t8_element_t *elem, int face) const;
 
+  /** Given an element and a face of an element as well as an ancestor of the element
+   * that has a face that is an ancestor of the given face, compute the corresponding face number of the ancestor element.
+   * 
+   * \param [in] tree_class    The eclass of the current tree.
+   * \param [in]  elem    An element.
+   * \param [in]  face    Then number of a face of \a element.
+   * \param [in]  ancestor An ancestor of \a element that has a common face with \a face. (Could be \a element itself).
+   * \return              The face number \a f_a corresponding to the face of with \a face is a asubface.
+   *                      <0 on failure.
+   */
+  inline int
+  element_face_get_ancestor_face (const t8_element_t *elem, const int face, const t8_element_t *ancestor) const
+  {
+    // For Quad elements the face number does not change when refining.
+    T8_ASSERT (element_is_valid (elem));
+    T8_ASSERT (element_is_valid (ancestor));
+    T8_ASSERT (0 <= face && face < element_get_num_face (elem));
+    T8_ASSERT (is_ancestor (ancestor, elem));
+    return face;
+  }
+
   /** Given an element and a face of this element. If the face lies on the
    *  tree boundary, return the face number of the tree face.
    *  If not the return value is arbitrary.

src/t8_schemes/t8_default/t8_default_tri/t8_default_tri.hxx

@@ -312,6 +312,27 @@ class t8_default_scheme_tri: public t8_default_scheme_common<t8_default_scheme_t
   int
   element_face_get_parent_face (const t8_element_t *elem, int face) const;
 
+  /** Given an element and a face of an element as well as an ancestor of the element
+   * that has a face that is an ancestor of the given face, compute the corresponding face number of the ancestor element.
+   * 
+   * \param [in] tree_class    The eclass of the current tree.
+   * \param [in]  elem    An element.
+   * \param [in]  face    Then number of a face of \a element.
+   * \param [in]  ancestor An ancestor of \a element that has a common face with \a face. (Could be \a element itself).
+   * \return              The face number \a f_a corresponding to the face of with \a face is a asubface.
+   *                      <0 on failure.
+   */
+  inline int
+  element_face_get_ancestor_face (const t8_element_t *elem, const int face, const t8_element_t *ancestor) const
+  {
+    // For Triangle elements the face number does not change when refining.
+    T8_ASSERT (element_is_valid (elem));
+    T8_ASSERT (element_is_valid (ancestor));
+    T8_ASSERT (0 <= face && face < element_get_num_face (elem));
+    T8_ASSERT (is_ancestor (ancestor, elem));
+    return face;
+  }
+
   /** Given an element and a face of this element. If the face lies on the tree boundary, return the face number of 
    * the tree face. If not the return value is arbitrary.
    * \param [in] elem     The element.

src/t8_schemes/t8_default/t8_default_vertex/t8_default_vertex.hxx

@@ -357,6 +357,27 @@ class t8_default_scheme_vertex: public t8_default_scheme_common<t8_default_schem
     return 0; /* prevents compiler warning */
   }
 
+  /** Given an element and a face of an element as well as an ancestor of the element
+   * that has a face that is an ancestor of the given face, compute the corresponding face number of the ancestor element.
+   * 
+   * \param [in] tree_class    The eclass of the current tree.
+   * \param [in]  elem    An element.
+   * \param [in]  face    Then number of a face of \a element.
+   * \param [in]  ancestor An ancestor of \a element that has a common face with \a face. (Could be \a element itself).
+   * \return              The face number \a f_a corresponding to the face of with \a face is a asubface.
+   *                      <0 on failure.
+   */
+  inline int
+  element_face_get_ancestor_face (const t8_element_t *elem, const int face, const t8_element_t *ancestor) const
+  {
+    // For vertex elements the face number does not change when refining.
+    T8_ASSERT (element_is_valid (elem));
+    T8_ASSERT (element_is_valid (ancestor));
+    T8_ASSERT (0 <= face && face < element_get_num_face (elem));
+    T8_ASSERT (is_ancestor (ancestor, elem));
+    return face;
+  }
+
   /** Given an element and a face of this element. If the face lies on the
    *  tree boundary, return the face number of the tree face.
    *  If not the return value is arbitrary.

src/t8_schemes/t8_scheme.hxx

@@ -613,6 +613,24 @@ class t8_scheme {
                        eclass_schemes[tree_class]);
   };
 
+  /** Given an element and a face of an element as well as an ancestor of the element
+   * that has a face that is an ancestor of the given face, compute the corresponding face number of the ancestor element.
+   * 
+   * \param [in] tree_class    The eclass of the current tree.
+   * \param [in]  elem    An element.
+   * \param [in]  face    Then number of a face of \a element.
+   * \param [in]  ancestor An ancestor of \a element that has a common face with \a face. (Could be \a element itself).
+   * \return              The face number \a f_a corresponding to the face of with \a face is a asubface.
+   *                      <0 on failure.
+   */
+  inline int
+  element_face_get_ancestor_face (const t8_eclass_t tree_class, const t8_element_t *elem, const int face,
+                                  const t8_element_t *ancestor) const
+  {
+    return std::visit ([&] (auto &&scheme) { return scheme.element_face_get_ancestor_face (elem, face, ancestor); },
+                       eclass_schemes[tree_class]);
+  };
+
   /** Given an element and a face of this element. If the face lies on the
    * tree boundary, return the face number of the tree face.
    * If not the return value is arbitrary.