From c477bbc73f5db8c6839d83792219bb6a3fe50df4 Mon Sep 17 00:00:00 2001
From: Johannes Holke <johannes.holke@dlr.de>
Date: Fri, 4 Jul 2025 15:09:07 +0200
Subject: [PATCH] Add declaration and first implementations of
 element_face_get_ancestor_face

---
 .../t8_default_hex/t8_default_hex.hxx         | 18 ++++++++++++++++
 .../t8_default_line/t8_default_line.hxx       | 21 +++++++++++++++++++
 .../t8_default_prism/t8_default_prism.hxx     | 21 +++++++++++++++++++
 .../t8_default_quad/t8_default_quad.hxx       | 21 +++++++++++++++++++
 .../t8_default_tri/t8_default_tri.hxx         | 21 +++++++++++++++++++
 .../t8_default_vertex/t8_default_vertex.hxx   | 21 +++++++++++++++++++
 src/t8_schemes/t8_scheme.hxx                  | 18 ++++++++++++++++
 7 files changed, 141 insertions(+)

diff --git a/src/t8_schemes/t8_default/t8_default_hex/t8_default_hex.hxx b/src/t8_schemes/t8_default/t8_default_hex/t8_default_hex.hxx
index 54ef5521b7..ea44bc240a 100644
--- a/src/t8_schemes/t8_default/t8_default_hex/t8_default_hex.hxx
+++ b/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.
diff --git a/src/t8_schemes/t8_default/t8_default_line/t8_default_line.hxx b/src/t8_schemes/t8_default/t8_default_line/t8_default_line.hxx
index 141347688f..f9ef0d5f7e 100644
--- a/src/t8_schemes/t8_default/t8_default_line/t8_default_line.hxx
+++ b/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.
diff --git a/src/t8_schemes/t8_default/t8_default_prism/t8_default_prism.hxx b/src/t8_schemes/t8_default/t8_default_prism/t8_default_prism.hxx
index 6032ad25a7..a7b2f2092a 100644
--- a/src/t8_schemes/t8_default/t8_default_prism/t8_default_prism.hxx
+++ b/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.
diff --git a/src/t8_schemes/t8_default/t8_default_quad/t8_default_quad.hxx b/src/t8_schemes/t8_default/t8_default_quad/t8_default_quad.hxx
index ecb03984b9..633fc6ba2e 100644
--- a/src/t8_schemes/t8_default/t8_default_quad/t8_default_quad.hxx
+++ b/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.
diff --git a/src/t8_schemes/t8_default/t8_default_tri/t8_default_tri.hxx b/src/t8_schemes/t8_default/t8_default_tri/t8_default_tri.hxx
index 08b974097f..b897f6aee4 100644
--- a/src/t8_schemes/t8_default/t8_default_tri/t8_default_tri.hxx
+++ b/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.
diff --git a/src/t8_schemes/t8_default/t8_default_vertex/t8_default_vertex.hxx b/src/t8_schemes/t8_default/t8_default_vertex/t8_default_vertex.hxx
index 2fab3b150e..dc025688ac 100644
--- a/src/t8_schemes/t8_default/t8_default_vertex/t8_default_vertex.hxx
+++ b/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.
diff --git a/src/t8_schemes/t8_scheme.hxx b/src/t8_schemes/t8_scheme.hxx
index f97d835729..98eb487a5f 100644
--- a/src/t8_schemes/t8_scheme.hxx
+++ b/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.