From fdc5f9ea65e54fa8f65ec7e4cba643caa867305b Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Wed, 29 Oct 2025 16:07:02 +0100
Subject: [PATCH 01/24] implement ghost class as child of element

---
 api/t8_mesh_handle/element.hxx                |  62 +++++++--
 api/t8_mesh_handle/ghost.hxx                  |  76 +++++++++++
 api/t8_mesh_handle/mesh.hxx                   |  59 +++++++--
 .../t8_gtest_cache_competence.cxx             |  10 +-
 test/api/t8_mesh_handle/t8_gtest_ghost.cxx    | 118 ++++++++++++++++++
 5 files changed, 304 insertions(+), 21 deletions(-)
 create mode 100644 api/t8_mesh_handle/ghost.hxx
 create mode 100644 test/api/t8_mesh_handle/t8_gtest_ghost.cxx

diff --git a/api/t8_mesh_handle/element.hxx b/api/t8_mesh_handle/element.hxx
index a5514f14b2..4c84df241f 100644
--- a/api/t8_mesh_handle/element.hxx
+++ b/api/t8_mesh_handle/element.hxx
@@ -32,6 +32,7 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8_eclass.h>
 #include <t8_forest/t8_forest_general.h>
 #include <t8_forest/t8_forest_geometrical.h>
+#include <t8_forest/t8_forest_balance.h>
 #include <t8_schemes/t8_scheme.hxx>
 #include <t8_types/t8_vec.hxx>
 #include <array>
@@ -41,7 +42,7 @@ namespace t8_mesh_handle
 {
 /* Forward declaration of the mesh class of the handle.
  */
-template <class TMeshElement>
+template <template <typename> class... TCompetence>
 class mesh;
 
 /** 
@@ -65,7 +66,7 @@ template <template <typename> class... TCompetence>
 class element: public TCompetence<element<TCompetence...>>... {
   using SelfType = element<TCompetence...>;
 
- private:
+ protected:
   // --- Variables to check which functionality is defined in TCompetence. ---
   /** Helper function to check if class T implements the function vertex_cache_filled.
    * \tparam T The competence to be checked.
@@ -102,7 +103,7 @@ class element: public TCompetence<element<TCompetence...>>... {
    * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
    * \param [in] element_id     The element id of the element in the forest defining the mesh.
    */
-  element (mesh<SelfType>* mesh, t8_locidx_t tree_id, t8_locidx_t element_id)
+  element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t element_id)
     : m_mesh (mesh), m_tree_id (tree_id), m_element_id (element_id)
   {
   }
@@ -128,6 +129,16 @@ class element: public TCompetence<element<TCompetence...>>... {
     return centroid_cache_exists;
   }
 
+
+  /**
+   * TODO
+   */
+  static constexpr bool
+  is_ghost_element ()
+  {
+    return false;
+  }
+
   // --- Functionality of the element. In each function, it is checked if a cached version exists (and is used then). ---
   /**
    * Getter for the refinement level of the mesh element.
@@ -142,6 +153,17 @@ class element: public TCompetence<element<TCompetence...>>... {
     return t8_forest_get_scheme (m_mesh->m_forest)->element_get_level (tree_class, element);
   }
 
+  /**
+   * Getter for the number of faces of the mesh element.
+   * For this easily accessible variable, it makes no sense to provide a cached version.
+   * \return Number of faces of the mesh element.
+   */
+  int
+  get_num_faces () const
+  {
+    return t8_forest_get_scheme (m_mesh->m_forest)->element_get_num_faces (get_tree_class (), get_element ());
+  }
+
   /**
    * Getter for the vertex coordinates of the mesh element.
    * This function uses or sets the cached version defined in TCompetence if available and calculates if not.
@@ -198,6 +220,30 @@ class element: public TCompetence<element<TCompetence...>>... {
     return coordinates;
   }
 
+  /** TODO*/
+  std::vector<t8_locidx_t>
+  get_face_neighbors (int face, int* num_neighbors, int* dual_faces[])
+  {
+    std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
+    t8_element_t** neighbors; /*< Neighboring elements. */
+    t8_locidx_t* neighids;    /*< Neighboring elements ids. */
+    t8_eclass_t neigh_class;  /*< Neighboring elements tree class. */
+    
+
+    t8_forest_leaf_face_neighbors (m_mesh->m_forest, m_tree_id, get_element (), &neighbors, face,
+                                   dual_faces, num_neighbors, &neighids, &neigh_class,
+                                   t8_forest_is_balanced (m_mesh->m_forest));
+    std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
+    if (*num_neighbors > 0) {
+      /* Free allocated memory. */
+      t8_forest_get_scheme (m_mesh->m_forest)
+        ->element_destroy (get_tree_class (), *num_neighbors, neighbors);
+      T8_FREE (neighbors);
+      T8_FREE (neighids);
+    }
+    return neighbor_ids_vector;
+  }
+
   //--- Getter for the member variables. ---
   /**
    * Getter for the tree id of the mesh element.
@@ -223,13 +269,13 @@ class element: public TCompetence<element<TCompetence...>>... {
    * Getter for the mesh to which the mesh element is belonging.
    * \return Reference to the mesh.
    */
-  const mesh<SelfType>*
+  const mesh<TCompetence...>*
   get_mesh () const
   {
     return m_mesh;
   }
 
- private:
+ protected:
   //--- Private getter for internal use. ---
   /**
    * Getter for the leaf element of the mesh element.
@@ -251,9 +297,9 @@ class element: public TCompetence<element<TCompetence...>>... {
     return t8_forest_get_tree_class (m_mesh->m_forest, m_tree_id);
   }
 
-  mesh<SelfType>* m_mesh;   /**< Pointer to the mesh the element is defined for. */
-  t8_locidx_t m_tree_id;    /**< The tree id of the element in the forest defined in the mesh. */
-  t8_locidx_t m_element_id; /**< The element id of the element in the forest defined in the mesh. */
+  mesh<TCompetence...>* m_mesh; /**< Pointer to the mesh the element is defined for. */
+  t8_locidx_t m_tree_id;        /**< The tree id of the element in the forest defined in the mesh. */
+  t8_locidx_t m_element_id;     /**< The element id of the element in the forest defined in the mesh. */
 };
 
 }  // namespace t8_mesh_handle
diff --git a/api/t8_mesh_handle/ghost.hxx b/api/t8_mesh_handle/ghost.hxx
new file mode 100644
index 0000000000..ee150e9a69
--- /dev/null
+++ b/api/t8_mesh_handle/ghost.hxx
@@ -0,0 +1,76 @@
+/*
+  This file is part of t8code.
+  t8code is a C library to manage a collection (a forest) of multiple
+  connected adaptive space-trees of general element classes in parallel.
+
+  Copyright (C) 2025 the developers
+
+  t8code is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  t8code is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with t8code; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/** \file ghost.hxx
+ * TODO
+ */
+
+#ifndef T8_GHOST_HXX
+#define T8_GHOST_HXX
+
+#include <t8.h>
+#include <t8_mesh_handle/element.hxx>
+#include <t8_forest/t8_forest_ghost.h>
+#include <vector>
+
+namespace t8_mesh_handle
+{
+    /* Forward declaration of the mesh class of the handle.
+ */
+template <template <typename> class... TCompetence>
+class mesh;
+
+template <template <typename> class... TCompetence>
+class ghost_element: public element<TCompetence...> {
+    public:
+  using Base = element<TCompetence...>;
+
+  ghost_element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t lghost_tree_id, t8_locidx_t element_id)
+    : Base (mesh, tree_id, element_id), m_lghost_tree_id (lghost_tree_id)
+  {
+  }
+
+   /**
+   * TODO
+   */
+  static constexpr bool
+  is_ghost_element ()
+  {
+    return true;
+  }
+
+  /** It is not possible for ghosts to compute their neighbors. */
+  std::vector<t8_locidx_t>
+  get_face_neighbors (int face, int* num_neighbors, int* dual_faces[]) = delete;
+
+ private:
+  const t8_element_t*
+  get_element () const
+  {
+    return t8_forest_ghost_get_leaf_element (this->m_mesh->m_forest, m_lghost_tree_id, this->m_element_id);
+  }
+
+  t8_locidx_t m_lghost_tree_id;
+};
+
+}  // namespace t8_mesh_handle
+#endif /* !T8_GHOST_HXX */
diff --git a/api/t8_mesh_handle/mesh.hxx b/api/t8_mesh_handle/mesh.hxx
index 56d4ae4b58..2c5dada927 100644
--- a/api/t8_mesh_handle/mesh.hxx
+++ b/api/t8_mesh_handle/mesh.hxx
@@ -30,6 +30,8 @@
 #include <t8.h>
 #include <t8_forest/t8_forest_general.h>
 #include <t8_mesh_handle/element.hxx>
+#include <t8_mesh_handle/ghost.hxx>
+#include <t8_forest/t8_forest_ghost.h>
 #include <iterator>
 #include <memory>
 #include <vector>
@@ -39,18 +41,20 @@ namespace t8_mesh_handle
 
 /**
  * Wrapper for a forest that enables it to be handled as a simple mesh object.
- * \tparam TMeshElement The element class that should be used for the elements in the mesh class. 
+ * \tparam TCompetence TODO The element class that should be used for the elements in the mesh class. 
  *                                  This template parameter defines which element functionality is available 
  *                                  and if it is cached or calculated.
  */
-template <class TMeshElement = element<>>
+template <template <typename> class... TCompetence>
 class mesh {
  public:
+  using mesh_element = element<TCompetence...>;
   // Declare mesh element as friend such that private members (e.g. the forest) can be accessed.
-  friend TMeshElement;
+  friend mesh_element;
 
-  using mesh_iterator = typename std::vector<TMeshElement>::iterator;
-  using mesh_const_iterator = typename std::vector<TMeshElement>::const_iterator;
+  using mesh_iterator = typename std::vector<mesh_element>::iterator;
+  using mesh_const_iterator = typename std::vector<mesh_element>::const_iterator;
+  using mesh_ghost_element = ghost_element<TCompetence...>;
 
   /** 
    * Constructor for a mesh of the handle. 
@@ -71,6 +75,16 @@ class mesh {
     return t8_forest_get_local_num_leaf_elements (m_forest);
   }
 
+  /**
+   * Getter for the number of local ghost elements.
+   * \return Number of local ghost elements in the unstructured mesh.
+   */
+  t8_locidx_t
+  get_local_num_ghosts () const
+  {
+    return t8_forest_get_num_ghosts (m_forest);
+  }
+
   /**
    * Returns an iterator to the first (local) mesh element.
    * \return Iterator to the first (local) mesh element.
@@ -116,10 +130,15 @@ class mesh {
    * \param [in] local_index The local index of the element to access.
    * \return Reference to the mesh element.
    */
-  TMeshElement&
+  mesh_element&
   operator[] (t8_locidx_t local_index)
   {
-    return m_elements[local_index];
+    if (local_index < get_local_num_elements ()) {
+      return m_elements[local_index];
+    }
+    else {
+      return m_ghosts[local_index - get_local_num_elements ()];
+    }
   }
 
   /**
@@ -162,10 +181,32 @@ class mesh {
         m_elements.emplace_back (this, itree, ielem);
       }
     }
+    update_ghost_elements ();
+  }
+
+  /** 
+   * Update the storage of the ghost elements according to the current forest. 
+   */
+  void
+  update_ghost_elements ()
+  {
+    if (!m_ghosts.empty ()) {
+      m_ghosts.clear ();
+    }
+    m_ghosts.reserve (get_local_num_ghosts ());
+    t8_locidx_t num_loc_trees = t8_forest_get_num_local_trees (m_forest);
+
+    for (t8_locidx_t itree = 0; itree < t8_forest_get_num_ghost_trees (m_forest); ++itree) {
+      const t8_locidx_t num_elems = t8_forest_ghost_tree_num_leaf_elements (m_forest, itree);
+      for (t8_locidx_t ielem = 0; ielem < num_elems; ++ielem) {
+        m_ghosts.emplace_back (this, num_loc_trees + itree, itree, ielem);
+      }
+    }
   }
 
-  t8_forest_t m_forest;                 /**< The forest the mesh should be defined for. */
-  std::vector<TMeshElement> m_elements; /**< Vector storing the mesh elements. */
+  t8_forest_t m_forest;                     /**< The forest the mesh should be defined for. */
+  std::vector<mesh_element> m_elements;     /**< Vector storing the (local) mesh elements. */
+  std::vector<mesh_ghost_element> m_ghosts; /**< Vector storing the (local) ghost elements. */
 };
 
 }  // namespace t8_mesh_handle
diff --git a/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx b/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
index 203bb3b38c..4e5e0d27fe 100644
--- a/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
@@ -99,8 +99,9 @@ TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
 {
   ASSERT_EQ (true, t8_forest_is_committed (forest));
 
-  using mesh_element = t8_mesh_handle::element<cache_vertex_coordinates_overwrite>;
-  t8_mesh_handle::mesh<mesh_element> mesh = t8_mesh_handle::mesh<mesh_element> (forest);
+  using mesh_class = t8_mesh_handle::mesh<cache_vertex_coordinates_overwrite>;
+  using mesh_element =mesh_class::mesh_element;
+  mesh_class mesh = mesh_class (forest);
   EXPECT_TRUE (mesh_element::has_vertex_cache ());
   EXPECT_FALSE (mesh_element::has_centroid_cache ());
 
@@ -133,8 +134,9 @@ TEST_F (t8_gtest_cache_competence, cache_centroid)
 {
   ASSERT_EQ (true, t8_forest_is_committed (forest));
 
-  using mesh_element = t8_mesh_handle::element<cache_centroid_overwrite>;
-  t8_mesh_handle::mesh<mesh_element> mesh = t8_mesh_handle::mesh<mesh_element> (forest);
+  using mesh_class = t8_mesh_handle::mesh<cache_centroid_overwrite>;
+  using mesh_element =mesh_class::mesh_element;
+  mesh_class mesh = mesh_class (forest);
   EXPECT_FALSE (mesh_element::has_vertex_cache ());
   EXPECT_TRUE (mesh_element::has_centroid_cache ());
 
diff --git a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
new file mode 100644
index 0000000000..2378b209de
--- /dev/null
+++ b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
@@ -0,0 +1,118 @@
+/*
+This file is part of t8code.
+t8code is a C library to manage a collection (a forest) of multiple
+connected adaptive space-trees of general element classes in parallel.
+
+Copyright (C) 2025 the developers
+
+t8code is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+t8code is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with t8code; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/**
+ * \file t8_gtest_mesh_handle.cxx
+ * Tests if the mesh class of the handle works as intended for different types of predefined template parameter classes. 
+ */
+
+#include <gtest/gtest.h>
+#include <test/t8_gtest_schemes.hxx>
+#include <test/t8_gtest_macros.hxx>
+#include <t8.h>
+
+#include <t8_mesh_handle/mesh.hxx>
+#include <t8_mesh_handle/element.hxx>
+#include <t8_mesh_handle/competences.hxx>
+#include <t8_mesh_handle/ghost.hxx>
+#include <t8_cmesh.h>
+#include <t8_cmesh/t8_cmesh_examples.h>
+#include <t8_forest/t8_forest_general.h>
+#include <t8_forest/t8_forest_ghost.h>
+#include <t8_schemes/t8_default/t8_default.hxx>
+
+/** Parametrized test fixture for the mesh handle tests. */
+class t8_mesh_handle_test: public testing::TestWithParam<std::tuple<t8_eclass_t, int>> {
+ protected:
+  void
+  SetUp () override
+  {
+    scheme = t8_scheme_new_default ();
+    eclass = std::get<0> (GetParam ());
+    level = std::get<1> (GetParam ());
+    t8_cmesh_t cmesh = t8_cmesh_new_hypercube (eclass, sc_MPI_COMM_WORLD, 0, 1, 0);
+    forest = t8_forest_new_uniform (cmesh, scheme, level, 1, sc_MPI_COMM_WORLD);
+  }
+  void
+  TearDown () override
+  {
+    t8_forest_unref (&forest);
+  }
+  t8_forest_t forest;
+  const t8_scheme* scheme;
+  t8_eclass_t eclass;
+  int level;
+};
+
+/** Test some default functionality and the iterator of \ref t8_mesh_handle::mesh class. */
+TEST_P (t8_mesh_handle_test, test_iterator)
+{
+  ASSERT_TRUE (t8_forest_is_committed (forest));
+  t8_forest_ghost_print (forest);
+
+  // --- Check default functionality. ---
+  t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
+  EXPECT_EQ(mesh.get_local_num_ghosts (),t8_forest_get_num_ghosts (forest));
+
+  // Iterate with the iterator over all mesh elements and check some functionality.
+  for (auto it = mesh.begin (); it != mesh.end (); ++it) {
+    EXPECT_FALSE(it->is_ghost_element ());
+    auto centroid = it->get_centroid ();
+    for (const auto& coordinate : centroid) {
+      EXPECT_GE (1, coordinate);
+      EXPECT_LE (0, coordinate);
+    }
+    auto vertex_coordinates = (*it).get_vertex_coordinates ();
+    for (int ivertex = 0; ivertex < (int) vertex_coordinates.size (); ++ivertex) {
+      for (const auto& coordinate : vertex_coordinates[ivertex]) {
+        EXPECT_GE (1, coordinate);
+        EXPECT_LE (0, coordinate);
+      }
+    }
+  }
+
+  for (int ighost=mesh.get_local_num_elements (); ighost<mesh.get_local_num_elements ()+mesh.get_local_num_ghosts (); ++ighost) {
+    
+    if (auto*  ghost = static_cast<t8_mesh_handle::ghost_element<>*>(&mesh[ighost])) {
+          EXPECT_TRUE(ghost->is_ghost_element ());
+    }
+
+    // Idea: virtual class element with childs mesh_element and ghost_element.
+    // Alternative is to let the user choose the right function ghost or not ghost with []. 
+
+    // auto centroid = it->get_centroid ();
+    // for (const auto& coordinate : centroid) {
+    //   EXPECT_GE (1, coordinate);
+    //   EXPECT_LE (0, coordinate);
+    // }
+    // auto vertex_coordinates = (*it).get_vertex_coordinates ();
+    // for (int ivertex = 0; ivertex < (int) vertex_coordinates.size (); ++ivertex) {
+    //   for (const auto& coordinate : vertex_coordinates[ivertex]) {
+    //     EXPECT_GE (1, coordinate);
+    //     EXPECT_LE (0, coordinate);
+    //   }
+    // }
+  }
+
+}
+
+INSTANTIATE_TEST_SUITE_P (t8_gtest_mesh, t8_mesh_handle_test, testing::Combine (AllEclasses, testing::Range (2, 3)));

From 3fa3ada36865ce3d79c2fbc492efd8a8786355e9 Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Wed, 29 Oct 2025 16:07:22 +0100
Subject: [PATCH 02/24] implement ghost class as child of element

---
 api/t8_mesh_handle/element.hxx                 | 10 +++-------
 api/t8_mesh_handle/ghost.hxx                   |  6 +++---
 .../t8_gtest_cache_competence.cxx              |  4 ++--
 test/api/t8_mesh_handle/t8_gtest_ghost.cxx     | 18 +++++++++---------
 4 files changed, 17 insertions(+), 21 deletions(-)

diff --git a/api/t8_mesh_handle/element.hxx b/api/t8_mesh_handle/element.hxx
index 4c84df241f..3539f0688e 100644
--- a/api/t8_mesh_handle/element.hxx
+++ b/api/t8_mesh_handle/element.hxx
@@ -129,7 +129,6 @@ class element: public TCompetence<element<TCompetence...>>... {
     return centroid_cache_exists;
   }
 
-
   /**
    * TODO
    */
@@ -228,16 +227,13 @@ class element: public TCompetence<element<TCompetence...>>... {
     t8_element_t** neighbors; /*< Neighboring elements. */
     t8_locidx_t* neighids;    /*< Neighboring elements ids. */
     t8_eclass_t neigh_class;  /*< Neighboring elements tree class. */
-    
 
-    t8_forest_leaf_face_neighbors (m_mesh->m_forest, m_tree_id, get_element (), &neighbors, face,
-                                   dual_faces, num_neighbors, &neighids, &neigh_class,
-                                   t8_forest_is_balanced (m_mesh->m_forest));
+    t8_forest_leaf_face_neighbors (m_mesh->m_forest, m_tree_id, get_element (), &neighbors, face, dual_faces,
+                                   num_neighbors, &neighids, &neigh_class, t8_forest_is_balanced (m_mesh->m_forest));
     std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
     if (*num_neighbors > 0) {
       /* Free allocated memory. */
-      t8_forest_get_scheme (m_mesh->m_forest)
-        ->element_destroy (get_tree_class (), *num_neighbors, neighbors);
+      t8_forest_get_scheme (m_mesh->m_forest)->element_destroy (get_tree_class (), *num_neighbors, neighbors);
       T8_FREE (neighbors);
       T8_FREE (neighids);
     }
diff --git a/api/t8_mesh_handle/ghost.hxx b/api/t8_mesh_handle/ghost.hxx
index ee150e9a69..0b8ce3cb5b 100644
--- a/api/t8_mesh_handle/ghost.hxx
+++ b/api/t8_mesh_handle/ghost.hxx
@@ -34,14 +34,14 @@
 
 namespace t8_mesh_handle
 {
-    /* Forward declaration of the mesh class of the handle.
+/* Forward declaration of the mesh class of the handle.
  */
 template <template <typename> class... TCompetence>
 class mesh;
 
 template <template <typename> class... TCompetence>
 class ghost_element: public element<TCompetence...> {
-    public:
+ public:
   using Base = element<TCompetence...>;
 
   ghost_element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t lghost_tree_id, t8_locidx_t element_id)
@@ -49,7 +49,7 @@ class ghost_element: public element<TCompetence...> {
   {
   }
 
-   /**
+  /**
    * TODO
    */
   static constexpr bool
diff --git a/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx b/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
index 4e5e0d27fe..e54d018945 100644
--- a/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
@@ -100,7 +100,7 @@ TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
   ASSERT_EQ (true, t8_forest_is_committed (forest));
 
   using mesh_class = t8_mesh_handle::mesh<cache_vertex_coordinates_overwrite>;
-  using mesh_element =mesh_class::mesh_element;
+  using mesh_element = mesh_class::mesh_element;
   mesh_class mesh = mesh_class (forest);
   EXPECT_TRUE (mesh_element::has_vertex_cache ());
   EXPECT_FALSE (mesh_element::has_centroid_cache ());
@@ -135,7 +135,7 @@ TEST_F (t8_gtest_cache_competence, cache_centroid)
   ASSERT_EQ (true, t8_forest_is_committed (forest));
 
   using mesh_class = t8_mesh_handle::mesh<cache_centroid_overwrite>;
-  using mesh_element =mesh_class::mesh_element;
+  using mesh_element = mesh_class::mesh_element;
   mesh_class mesh = mesh_class (forest);
   EXPECT_FALSE (mesh_element::has_vertex_cache ());
   EXPECT_TRUE (mesh_element::has_centroid_cache ());
diff --git a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
index 2378b209de..85af0b1d0b 100644
--- a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
@@ -71,11 +71,11 @@ TEST_P (t8_mesh_handle_test, test_iterator)
 
   // --- Check default functionality. ---
   t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
-  EXPECT_EQ(mesh.get_local_num_ghosts (),t8_forest_get_num_ghosts (forest));
+  EXPECT_EQ (mesh.get_local_num_ghosts (), t8_forest_get_num_ghosts (forest));
 
   // Iterate with the iterator over all mesh elements and check some functionality.
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
-    EXPECT_FALSE(it->is_ghost_element ());
+    EXPECT_FALSE (it->is_ghost_element ());
     auto centroid = it->get_centroid ();
     for (const auto& coordinate : centroid) {
       EXPECT_GE (1, coordinate);
@@ -90,14 +90,15 @@ TEST_P (t8_mesh_handle_test, test_iterator)
     }
   }
 
-  for (int ighost=mesh.get_local_num_elements (); ighost<mesh.get_local_num_elements ()+mesh.get_local_num_ghosts (); ++ighost) {
-    
-    if (auto*  ghost = static_cast<t8_mesh_handle::ghost_element<>*>(&mesh[ighost])) {
-          EXPECT_TRUE(ghost->is_ghost_element ());
+  for (int ighost = mesh.get_local_num_elements ();
+       ighost < mesh.get_local_num_elements () + mesh.get_local_num_ghosts (); ++ighost) {
+
+    if (auto* ghost = static_cast<t8_mesh_handle::ghost_element<>*> (&mesh[ighost])) {
+      EXPECT_TRUE (ghost->is_ghost_element ());
     }
 
-    // Idea: virtual class element with childs mesh_element and ghost_element.
-    // Alternative is to let the user choose the right function ghost or not ghost with []. 
+    // Idea: virtual class element with children mesh_element and ghost_element.
+    // Alternative is to let the user choose the right function ghost or not ghost with [].
 
     // auto centroid = it->get_centroid ();
     // for (const auto& coordinate : centroid) {
@@ -112,7 +113,6 @@ TEST_P (t8_mesh_handle_test, test_iterator)
     //   }
     // }
   }
-
 }
 
 INSTANTIATE_TEST_SUITE_P (t8_gtest_mesh, t8_mesh_handle_test, testing::Combine (AllEclasses, testing::Range (2, 3)));

From 1f405a8524df8494d20bbf863b1e4169cc3beb1d Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Thu, 30 Oct 2025 08:21:20 +0100
Subject: [PATCH 03/24] adapt all tests

---
 test/CMakeLists.txt                           |  9 +++---
 .../t8_gtest_compare_handle_to_forest.cxx     |  2 +-
 .../t8_gtest_custom_competence.cxx            | 11 +++----
 .../t8_mesh_handle/t8_gtest_mesh_handle.cxx   | 29 ++++++++++---------
 4 files changed, 26 insertions(+), 25 deletions(-)

diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index 98473ce68b..c3ab32a16e 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -202,10 +202,11 @@ endif()
 add_t8_cpp_test( NAME t8_gtest_vector_split_serial               SOURCES t8_vector_helper/t8_gtest_vector_split.cxx )
   
 if( T8CODE_BUILD_MESH_HANDLE )
-  add_t8_cpp_test( NAME t8_gtest_mesh_handle_parallel             SOURCES api/t8_mesh_handle/t8_gtest_mesh_handle.cxx )
-  add_t8_cpp_test( NAME t8_gtest_compare_handle_to_forest_serial  SOURCES api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx )
-  add_t8_cpp_test( NAME t8_gtest_custom_competence_serial         SOURCES api/t8_mesh_handle/t8_gtest_custom_competence.cxx )
-  add_t8_cpp_test( NAME t8_gtest_cache_competence_serial          SOURCES api/t8_mesh_handle/t8_gtest_cache_competence.cxx )
+   add_t8_cpp_test( NAME t8_gtest_mesh_handle_parallel             SOURCES api/t8_mesh_handle/t8_gtest_mesh_handle.cxx )
+   add_t8_cpp_test( NAME t8_gtest_compare_handle_to_forest_serial  SOURCES api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx )
+   add_t8_cpp_test( NAME t8_gtest_ghost_parallel                   SOURCES api/t8_mesh_handle/t8_gtest_ghost.cxx )
+   add_t8_cpp_test( NAME t8_gtest_custom_competence_serial         SOURCES api/t8_mesh_handle/t8_gtest_custom_competence.cxx )
+   add_t8_cpp_test( NAME t8_gtest_cache_competence_serial          SOURCES api/t8_mesh_handle/t8_gtest_cache_competence.cxx )
 endif()
 
 copy_test_file( test_cube_unstructured_1.inp )
diff --git a/test/api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx b/test/api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx
index dd9b617cb4..8b1681e26c 100644
--- a/test/api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx
@@ -47,7 +47,7 @@ TEST (t8_gtest_compare_handle_to_forest, compare_handle_to_forest)
   t8_forest_t forest = t8_forest_new_uniform (cmesh, init_scheme, level, 0, sc_MPI_COMM_WORLD);
   ASSERT_EQ (true, t8_forest_is_committed (forest));
 
-  t8_mesh_handle::mesh<t8_mesh_handle::element<>> mesh = t8_mesh_handle::mesh<t8_mesh_handle::element<>> (forest);
+  t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
 
   const t8_scheme *scheme = t8_forest_get_scheme (forest);
   auto mesh_iterator = mesh.cbegin ();
diff --git a/test/api/t8_mesh_handle/t8_gtest_custom_competence.cxx b/test/api/t8_mesh_handle/t8_gtest_custom_competence.cxx
index b952cba03f..b207048a17 100644
--- a/test/api/t8_mesh_handle/t8_gtest_custom_competence.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_custom_competence.cxx
@@ -80,8 +80,7 @@ TEST (t8_gtest_custom_competence, custom_competence)
   ASSERT_EQ (true, t8_forest_is_committed (forest));
 
   // Check mesh with custom defined competence.
-  t8_mesh_handle::mesh<t8_mesh_handle::element<dummy_get_level>> mesh
-    = t8_mesh_handle::mesh<t8_mesh_handle::element<dummy_get_level>> (forest);
+  t8_mesh_handle::mesh<dummy_get_level> mesh = t8_mesh_handle::mesh<dummy_get_level> (forest);
 
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
     EXPECT_EQ (it->get_level (), it->get_level_dummy ());
@@ -89,12 +88,10 @@ TEST (t8_gtest_custom_competence, custom_competence)
   }
 
   // Test with two custom competences and a predefined competence.
-  t8_mesh_handle::mesh<t8_mesh_handle::element<dummy_get_level, dummy_trivial, t8_mesh_handle::cache_centroid>>
-    mesh_2competences
-    = t8_mesh_handle::mesh<t8_mesh_handle::element<dummy_get_level, dummy_trivial, t8_mesh_handle::cache_centroid>> (
-      forest);
+  using mesh_class = t8_mesh_handle::mesh<dummy_get_level, dummy_trivial, t8_mesh_handle::cache_centroid>;
+  mesh_class mesh_more_competences = mesh_class (forest);
 
-  for (auto it = mesh_2competences.begin (); it != mesh_2competences.end (); ++it) {
+  for (auto it = mesh_more_competences.begin (); it != mesh_more_competences.end (); ++it) {
     EXPECT_EQ (it->get_level (), it->get_level_dummy ());
     EXPECT_EQ (it->get_value_dummy (), 1);
     EXPECT_FALSE (it->centroid_cache_filled ());
diff --git a/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx b/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
index 535c892d18..a1793c319e 100644
--- a/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
@@ -67,9 +67,11 @@ TEST_P (t8_mesh_handle_test, test_iterator)
   ASSERT_TRUE (t8_forest_is_committed (forest));
 
   // --- Check default functionality. ---
-  t8_mesh_handle::mesh<t8_mesh_handle::element<>> mesh = t8_mesh_handle::mesh<t8_mesh_handle::element<>> (forest);
-  EXPECT_FALSE (t8_mesh_handle::element<>::has_vertex_cache ());
-  EXPECT_FALSE (t8_mesh_handle::element<>::has_centroid_cache ());
+  using mesh_class = t8_mesh_handle::mesh<>;
+  using mesh_element = mesh_class::mesh_element;
+  mesh_class mesh = mesh_class (forest);
+  EXPECT_FALSE (mesh_element::has_vertex_cache ());
+  EXPECT_FALSE (mesh_element::has_centroid_cache ());
 
   // Iterate with the iterator over all mesh elements and check some functionality.
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
@@ -106,14 +108,14 @@ TEST_P (t8_mesh_handle_test, test_competences)
   ASSERT_TRUE (t8_forest_is_committed (forest));
 
   // --- Version with cached vertex coordinates. ---
-  using mesh_element_vertex = t8_mesh_handle::element<t8_mesh_handle::cache_vertex_coordinates>;
-  t8_mesh_handle::mesh<mesh_element_vertex> mesh_vertex_coordinates
-    = t8_mesh_handle::mesh<mesh_element_vertex> (forest);
+  using mesh_class_vertex = t8_mesh_handle::mesh<t8_mesh_handle::cache_vertex_coordinates>;
+  using mesh_element_vertex = mesh_class_vertex::mesh_element;
+  mesh_class_vertex mesh_vertex = mesh_class_vertex (forest);
   EXPECT_TRUE (mesh_element_vertex::has_vertex_cache ());
   EXPECT_FALSE (mesh_element_vertex::has_centroid_cache ());
 
   // Iterate with the iterator over all mesh elements and check functionality.
-  for (auto it = mesh_vertex_coordinates.begin (); it != mesh_vertex_coordinates.end (); ++it) {
+  for (auto it = mesh_vertex.begin (); it != mesh_vertex.end (); ++it) {
     EXPECT_FALSE (it->vertex_cache_filled ());
     EXPECT_EQ (level, it->get_level ());
     auto centroid = it->get_centroid ();
@@ -130,7 +132,7 @@ TEST_P (t8_mesh_handle_test, test_competences)
     }
   }
   // Check cached value.
-  for (auto it = mesh_vertex_coordinates.begin (); it != mesh_vertex_coordinates.end (); ++it) {
+  for (auto it = mesh_vertex.begin (); it != mesh_vertex.end (); ++it) {
     EXPECT_TRUE (it->vertex_cache_filled ());
     auto vertex_coordinates = it->get_vertex_coordinates ();
     for (int ivertex = 0; ivertex < (int) vertex_coordinates.size (); ++ivertex) {
@@ -142,8 +144,9 @@ TEST_P (t8_mesh_handle_test, test_competences)
   }
 
   // --- Version with cached centroid variable. ---
-  using mesh_element_centroid = t8_mesh_handle::element<t8_mesh_handle::cache_centroid>;
-  t8_mesh_handle::mesh<mesh_element_centroid> mesh_centroid = t8_mesh_handle::mesh<mesh_element_centroid> (forest);
+  using mesh_class_centroid = t8_mesh_handle::mesh<t8_mesh_handle::cache_centroid>;
+  using mesh_element_centroid = mesh_class_centroid::mesh_element;
+  mesh_class_centroid mesh_centroid = mesh_class_centroid (forest);
   EXPECT_FALSE (mesh_element_centroid::has_vertex_cache ());
   EXPECT_TRUE (mesh_element_centroid::has_centroid_cache ());
 
@@ -170,9 +173,9 @@ TEST_P (t8_mesh_handle_test, test_2_competences)
   ASSERT_TRUE (t8_forest_is_committed (forest));
 
   // --- Use competences to cache level and centroid. ---
-  using mesh_element
-    = t8_mesh_handle::element<t8_mesh_handle::cache_vertex_coordinates, t8_mesh_handle::cache_centroid>;
-  t8_mesh_handle::mesh<mesh_element> mesh = t8_mesh_handle::mesh<mesh_element> (forest);
+  using mesh_class = t8_mesh_handle::mesh<t8_mesh_handle::cache_vertex_coordinates, t8_mesh_handle::cache_centroid>;
+  using mesh_element = mesh_class::mesh_element;
+  mesh_class mesh = mesh_class (forest);
   EXPECT_TRUE (mesh_element::has_vertex_cache ());
   EXPECT_TRUE (mesh_element::has_centroid_cache ());
 

From 04ed7a16d0adcfa17b8b993b103da835f3e626f1 Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Thu, 30 Oct 2025 09:41:13 +0100
Subject: [PATCH 04/24] make constructors of elements private

---
 api/t8_mesh_handle/element.hxx | 4 +++-
 api/t8_mesh_handle/ghost.hxx   | 5 ++++-
 api/t8_mesh_handle/mesh.hxx    | 4 ++--
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/api/t8_mesh_handle/element.hxx b/api/t8_mesh_handle/element.hxx
index 3539f0688e..e72193e90b 100644
--- a/api/t8_mesh_handle/element.hxx
+++ b/api/t8_mesh_handle/element.hxx
@@ -65,6 +65,8 @@ class mesh;
 template <template <typename> class... TCompetence>
 class element: public TCompetence<element<TCompetence...>>... {
   using SelfType = element<TCompetence...>;
+  using mesh_class = mesh<TCompetence...>;
+  friend mesh_class;
 
  protected:
   // --- Variables to check which functionality is defined in TCompetence. ---
@@ -96,7 +98,6 @@ class element: public TCompetence<element<TCompetence...>>... {
   a function centroid_cache_filled. */
   static constexpr bool centroid_cache_exists = (false || ... || centroid_cache_defined<TCompetence> ());
 
- public:
   /**
    * Constructor for an element of a mesh.
    * \param [in] mesh           Pointer to the mesh the element should belong to.
@@ -108,6 +109,7 @@ class element: public TCompetence<element<TCompetence...>>... {
   {
   }
 
+ public:
   // --- Functions to check if caches exist. ---
   /**
    * Function that checks if a cache for the vertex coordinates exists.
diff --git a/api/t8_mesh_handle/ghost.hxx b/api/t8_mesh_handle/ghost.hxx
index 0b8ce3cb5b..fae34e9d18 100644
--- a/api/t8_mesh_handle/ghost.hxx
+++ b/api/t8_mesh_handle/ghost.hxx
@@ -41,14 +41,17 @@ class mesh;
 
 template <template <typename> class... TCompetence>
 class ghost_element: public element<TCompetence...> {
- public:
   using Base = element<TCompetence...>;
+  using mesh_class = mesh<TCompetence...>;
+  friend mesh_class;
 
+ protected:
   ghost_element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t lghost_tree_id, t8_locidx_t element_id)
     : Base (mesh, tree_id, element_id), m_lghost_tree_id (lghost_tree_id)
   {
   }
 
+ public:
   /**
    * TODO
    */
diff --git a/api/t8_mesh_handle/mesh.hxx b/api/t8_mesh_handle/mesh.hxx
index 2c5dada927..671ec8e8a1 100644
--- a/api/t8_mesh_handle/mesh.hxx
+++ b/api/t8_mesh_handle/mesh.hxx
@@ -178,7 +178,7 @@ class mesh {
     for (t8_locidx_t itree = 0; itree < t8_forest_get_num_local_trees (m_forest); ++itree) {
       const t8_locidx_t num_elems = t8_forest_get_tree_num_leaf_elements (m_forest, itree);
       for (t8_locidx_t ielem = 0; ielem < num_elems; ++ielem) {
-        m_elements.emplace_back (this, itree, ielem);
+        m_elements.push_back (mesh_element (this, itree, ielem));
       }
     }
     update_ghost_elements ();
@@ -199,7 +199,7 @@ class mesh {
     for (t8_locidx_t itree = 0; itree < t8_forest_get_num_ghost_trees (m_forest); ++itree) {
       const t8_locidx_t num_elems = t8_forest_ghost_tree_num_leaf_elements (m_forest, itree);
       for (t8_locidx_t ielem = 0; ielem < num_elems; ++ielem) {
-        m_ghosts.emplace_back (this, num_loc_trees + itree, itree, ielem);
+        m_ghosts.push_back (mesh_ghost_element (this, num_loc_trees + itree, itree, ielem));
       }
     }
   }

From 6c2f9eea9ef6216da34e407f7c08819e457db6ff Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Thu, 30 Oct 2025 17:03:09 +0100
Subject: [PATCH 05/24] abstract class for elements

---
 .../{element.hxx => abstract_element.hxx}     |  67 +++------
 .../{ghost.hxx => ghost_element.hxx}          |  23 ++-
 api/t8_mesh_handle/mesh.hxx                   |  30 ++--
 api/t8_mesh_handle/mesh_element.hxx           | 135 ++++++++++++++++++
 test/CMakeLists.txt                           |   8 +-
 test/api/t8_mesh_handle/t8_gtest_ghost.cxx    | 111 ++++++++++----
 .../t8_mesh_handle/t8_gtest_mesh_handle.cxx   |  26 ++--
 7 files changed, 282 insertions(+), 118 deletions(-)
 rename api/t8_mesh_handle/{element.hxx => abstract_element.hxx} (86%)
 rename api/t8_mesh_handle/{ghost.hxx => ghost_element.hxx} (78%)
 create mode 100644 api/t8_mesh_handle/mesh_element.hxx

diff --git a/api/t8_mesh_handle/element.hxx b/api/t8_mesh_handle/abstract_element.hxx
similarity index 86%
rename from api/t8_mesh_handle/element.hxx
rename to api/t8_mesh_handle/abstract_element.hxx
index e72193e90b..8e0a654f85 100644
--- a/api/t8_mesh_handle/element.hxx
+++ b/api/t8_mesh_handle/abstract_element.hxx
@@ -24,8 +24,8 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
  * Definition of the elements used in the mesh class.
  */
 
-#ifndef T8_ELEMENT_HXX
-#define T8_ELEMENT_HXX
+#ifndef T8_ABSTRACT_ELEMENT_HXX
+#define T8_ABSTRACT_ELEMENT_HXX
 
 #include <t8.h>
 #include <t8_element.h>
@@ -63,12 +63,23 @@ class mesh;
  * \tparam TCompetence The competences you want to add to the default functionality of the element.
  */
 template <template <typename> class... TCompetence>
-class element: public TCompetence<element<TCompetence...>>... {
-  using SelfType = element<TCompetence...>;
+class abstract_element: public TCompetence<abstract_element<TCompetence...>>... {
+ protected:
+  using SelfType = abstract_element<TCompetence...>;
   using mesh_class = mesh<TCompetence...>;
   friend mesh_class;
 
- protected:
+  /**
+   * Constructor for an element of a mesh.
+   * \param [in] mesh           Pointer to the mesh the element should belong to.
+   * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
+   * \param [in] element_id     The element id of the element in the forest defining the mesh.
+   */
+  abstract_element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t element_id)
+    : m_mesh (mesh), m_tree_id (tree_id), m_element_id (element_id)
+  {
+  }
+
   // --- Variables to check which functionality is defined in TCompetence. ---
   /** Helper function to check if class T implements the function vertex_cache_filled.
    * \tparam T The competence to be checked.
@@ -98,17 +109,6 @@ class element: public TCompetence<element<TCompetence...>>... {
   a function centroid_cache_filled. */
   static constexpr bool centroid_cache_exists = (false || ... || centroid_cache_defined<TCompetence> ());
 
-  /**
-   * Constructor for an element of a mesh.
-   * \param [in] mesh           Pointer to the mesh the element should belong to.
-   * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
-   * \param [in] element_id     The element id of the element in the forest defining the mesh.
-   */
-  element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t element_id)
-    : m_mesh (mesh), m_tree_id (tree_id), m_element_id (element_id)
-  {
-  }
-
  public:
   // --- Functions to check if caches exist. ---
   /**
@@ -134,11 +134,9 @@ class element: public TCompetence<element<TCompetence...>>... {
   /**
    * TODO
    */
-  static constexpr bool
+  virtual constexpr bool
   is_ghost_element ()
-  {
-    return false;
-  }
+    = 0;
 
   // --- Functionality of the element. In each function, it is checked if a cached version exists (and is used then). ---
   /**
@@ -221,27 +219,6 @@ class element: public TCompetence<element<TCompetence...>>... {
     return coordinates;
   }
 
-  /** TODO*/
-  std::vector<t8_locidx_t>
-  get_face_neighbors (int face, int* num_neighbors, int* dual_faces[])
-  {
-    std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
-    t8_element_t** neighbors; /*< Neighboring elements. */
-    t8_locidx_t* neighids;    /*< Neighboring elements ids. */
-    t8_eclass_t neigh_class;  /*< Neighboring elements tree class. */
-
-    t8_forest_leaf_face_neighbors (m_mesh->m_forest, m_tree_id, get_element (), &neighbors, face, dual_faces,
-                                   num_neighbors, &neighids, &neigh_class, t8_forest_is_balanced (m_mesh->m_forest));
-    std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
-    if (*num_neighbors > 0) {
-      /* Free allocated memory. */
-      t8_forest_get_scheme (m_mesh->m_forest)->element_destroy (get_tree_class (), *num_neighbors, neighbors);
-      T8_FREE (neighbors);
-      T8_FREE (neighids);
-    }
-    return neighbor_ids_vector;
-  }
-
   //--- Getter for the member variables. ---
   /**
    * Getter for the tree id of the mesh element.
@@ -279,11 +256,9 @@ class element: public TCompetence<element<TCompetence...>>... {
    * Getter for the leaf element of the mesh element.
    * \return The leaf element.
    */
-  const t8_element_t*
+  virtual const t8_element_t*
   get_element () const
-  {
-    return t8_forest_get_leaf_element_in_tree (m_mesh->m_forest, m_tree_id, m_element_id);
-  }
+    = 0;
 
   /**
    * Getter for the eclass of the mesh element.
@@ -301,4 +276,4 @@ class element: public TCompetence<element<TCompetence...>>... {
 };
 
 }  // namespace t8_mesh_handle
-#endif /* !T8_ELEMENT_HXX */
+#endif /* !T8_ABSTRACT_ELEMENT_HXX */
diff --git a/api/t8_mesh_handle/ghost.hxx b/api/t8_mesh_handle/ghost_element.hxx
similarity index 78%
rename from api/t8_mesh_handle/ghost.hxx
rename to api/t8_mesh_handle/ghost_element.hxx
index fae34e9d18..1b776461f9 100644
--- a/api/t8_mesh_handle/ghost.hxx
+++ b/api/t8_mesh_handle/ghost_element.hxx
@@ -24,11 +24,11 @@
  * TODO
  */
 
-#ifndef T8_GHOST_HXX
-#define T8_GHOST_HXX
+#ifndef T8_GHOST_ELEMENT_HXX
+#define T8_GHOST_ELEMENT_HXX
 
 #include <t8.h>
-#include <t8_mesh_handle/element.hxx>
+#include <t8_mesh_handle/abstract_element.hxx>
 #include <t8_forest/t8_forest_ghost.h>
 #include <vector>
 
@@ -40,12 +40,11 @@ template <template <typename> class... TCompetence>
 class mesh;
 
 template <template <typename> class... TCompetence>
-class ghost_element: public element<TCompetence...> {
-  using Base = element<TCompetence...>;
+class ghost_element: public abstract_element<TCompetence...> {
+  using Base = abstract_element<TCompetence...>;
   using mesh_class = mesh<TCompetence...>;
   friend mesh_class;
 
- protected:
   ghost_element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t lghost_tree_id, t8_locidx_t element_id)
     : Base (mesh, tree_id, element_id), m_lghost_tree_id (lghost_tree_id)
   {
@@ -55,15 +54,15 @@ class ghost_element: public element<TCompetence...> {
   /**
    * TODO
    */
-  static constexpr bool
-  is_ghost_element ()
+  constexpr bool
+  is_ghost_element () override
   {
     return true;
   }
 
-  /** It is not possible for ghosts to compute their neighbors. */
-  std::vector<t8_locidx_t>
-  get_face_neighbors (int face, int* num_neighbors, int* dual_faces[]) = delete;
+  // /** It is not possible for ghosts to compute their neighbors. */
+  // std::vector<t8_locidx_t>
+  // get_face_neighbors (int face, int* num_neighbors, int* dual_faces[]) =delete;
 
  private:
   const t8_element_t*
@@ -76,4 +75,4 @@ class ghost_element: public element<TCompetence...> {
 };
 
 }  // namespace t8_mesh_handle
-#endif /* !T8_GHOST_HXX */
+#endif /* !T8_GHOST_ELEMENT_HXX */
diff --git a/api/t8_mesh_handle/mesh.hxx b/api/t8_mesh_handle/mesh.hxx
index 671ec8e8a1..316b61017a 100644
--- a/api/t8_mesh_handle/mesh.hxx
+++ b/api/t8_mesh_handle/mesh.hxx
@@ -29,8 +29,9 @@
 
 #include <t8.h>
 #include <t8_forest/t8_forest_general.h>
-#include <t8_mesh_handle/element.hxx>
-#include <t8_mesh_handle/ghost.hxx>
+#include <t8_mesh_handle/abstract_element.hxx>
+#include <t8_mesh_handle/mesh_element.hxx>
+#include <t8_mesh_handle/ghost_element.hxx>
 #include <t8_forest/t8_forest_ghost.h>
 #include <iterator>
 #include <memory>
@@ -48,13 +49,16 @@ namespace t8_mesh_handle
 template <template <typename> class... TCompetence>
 class mesh {
  public:
-  using mesh_element = element<TCompetence...>;
+  using abstract_element_class = abstract_element<TCompetence...>;
+  using mesh_element_class = mesh_element<TCompetence...>;
+  using ghost_element_class = ghost_element<TCompetence...>;
   // Declare mesh element as friend such that private members (e.g. the forest) can be accessed.
-  friend mesh_element;
+  friend abstract_element_class;
+  friend mesh_element_class;
+  friend ghost_element_class;
 
-  using mesh_iterator = typename std::vector<mesh_element>::iterator;
-  using mesh_const_iterator = typename std::vector<mesh_element>::const_iterator;
-  using mesh_ghost_element = ghost_element<TCompetence...>;
+  using mesh_iterator = typename std::vector<mesh_element_class>::iterator;
+  using mesh_const_iterator = typename std::vector<mesh_element_class>::const_iterator;
 
   /** 
    * Constructor for a mesh of the handle. 
@@ -130,7 +134,7 @@ class mesh {
    * \param [in] local_index The local index of the element to access.
    * \return Reference to the mesh element.
    */
-  mesh_element&
+  abstract_element_class&
   operator[] (t8_locidx_t local_index)
   {
     if (local_index < get_local_num_elements ()) {
@@ -178,7 +182,7 @@ class mesh {
     for (t8_locidx_t itree = 0; itree < t8_forest_get_num_local_trees (m_forest); ++itree) {
       const t8_locidx_t num_elems = t8_forest_get_tree_num_leaf_elements (m_forest, itree);
       for (t8_locidx_t ielem = 0; ielem < num_elems; ++ielem) {
-        m_elements.push_back (mesh_element (this, itree, ielem));
+        m_elements.push_back (mesh_element_class (this, itree, ielem));
       }
     }
     update_ghost_elements ();
@@ -199,14 +203,14 @@ class mesh {
     for (t8_locidx_t itree = 0; itree < t8_forest_get_num_ghost_trees (m_forest); ++itree) {
       const t8_locidx_t num_elems = t8_forest_ghost_tree_num_leaf_elements (m_forest, itree);
       for (t8_locidx_t ielem = 0; ielem < num_elems; ++ielem) {
-        m_ghosts.push_back (mesh_ghost_element (this, num_loc_trees + itree, itree, ielem));
+        m_ghosts.push_back (ghost_element_class (this, num_loc_trees + itree, itree, ielem));
       }
     }
   }
 
-  t8_forest_t m_forest;                     /**< The forest the mesh should be defined for. */
-  std::vector<mesh_element> m_elements;     /**< Vector storing the (local) mesh elements. */
-  std::vector<mesh_ghost_element> m_ghosts; /**< Vector storing the (local) ghost elements. */
+  t8_forest_t m_forest;                       /**< The forest the mesh should be defined for. */
+  std::vector<mesh_element_class> m_elements; /**< Vector storing the (local) mesh elements. */
+  std::vector<ghost_element_class> m_ghosts;  /**< Vector storing the (local) ghost elements. */
 };
 
 }  // namespace t8_mesh_handle
diff --git a/api/t8_mesh_handle/mesh_element.hxx b/api/t8_mesh_handle/mesh_element.hxx
new file mode 100644
index 0000000000..c8910886a4
--- /dev/null
+++ b/api/t8_mesh_handle/mesh_element.hxx
@@ -0,0 +1,135 @@
+/*
+This file is part of t8code.
+t8code is a C library to manage a collection (a forest) of multiple
+connected adaptive space-trees of general element classes in parallel.
+
+Copyright (C) 2025 the developers
+
+t8code is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+t8code is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with t8code; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/** \file element.hxx TODO
+ * Definition of the elements used in the mesh class.
+ */
+
+#ifndef T8_MESH_ELEMENT_HXX
+#define T8_MESH_ELEMENT_HXX
+
+#include <t8_mesh_handle/abstract_element.hxx>
+#include <t8.h>
+#include <t8_element.h>
+#include <t8_eclass.h>
+#include <t8_forest/t8_forest_general.h>
+#include <t8_forest/t8_forest_geometrical.h>
+#include <t8_forest/t8_forest_balance.h>
+#include <t8_schemes/t8_scheme.hxx>
+#include <t8_types/t8_vec.hxx>
+#include <array>
+#include <vector>
+
+namespace t8_mesh_handle
+{
+/* Forward declaration of the mesh class of the handle.
+ */
+template <template <typename> class... TCompetence>
+class mesh;
+
+/** 
+ * Class for the elements of the mesh handle. 
+ * The element without specified template parameters provides default implementations for basic functionality 
+ * as accessing the refinement level or the centroid. With this implementation, the functionality is calculated each time
+ * the function is called. 
+ * Use the competences defined in competences.hxx as template parameter to cache the functionality instead of 
+ * recalculating in every function call.
+ * To add functionality to the element, you can also simply write your own competence class and give it as a template parameter.
+ * You can access the functions implemented in your competence via the element. 
+ *
+ * The inheritance pattern is inspired by the \ref T8Type class (which also uses the CRTP).
+ * We decided to use this structure 1.) to be able to add new functionality easily and 
+ *    2.) for the cached options to keep the number of class member variables of the default to a minimum to save memory.
+ * The choice between calculate and cache is a tradeoff between runtime and memory usage. 
+ *
+ * \tparam TCompetence The competences you want to add to the default functionality of the element.
+ */
+template <template <typename> class... TCompetence>
+class mesh_element: public abstract_element<TCompetence...> {
+  using Base = abstract_element<TCompetence...>;
+  using SelfType = mesh_element<TCompetence...>;
+  using mesh_class = Base::mesh_class;
+  friend mesh_class;
+
+  /**
+   * Constructor for an element of a mesh.
+   * \param [in] mesh           Pointer to the mesh the element should belong to.
+   * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
+   * \param [in] element_id     The element id of the element in the forest defining the mesh.
+   */
+  mesh_element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t element_id)
+    : Base (mesh, tree_id, element_id)
+  {
+  }
+
+ public:
+  // --- Functions to check if caches exist. ---
+
+  /**
+   * TODO
+   */
+  constexpr bool
+  is_ghost_element () override
+  {
+    return false;
+  }
+
+  // --- Functionality of the element. In each function, it is checked if a cached version exists (and is used then). ---
+
+  /** TODO*/
+  std::vector<t8_locidx_t>
+  get_face_neighbors (int face, int* num_neighbors, int* dual_faces[]) const
+  {
+    std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
+    t8_element_t** neighbors; /*< Neighboring elements. */
+    t8_locidx_t* neighids;    /*< Neighboring elements ids. */
+    t8_eclass_t neigh_class;  /*< Neighboring elements tree class. */
+
+    t8_forest_leaf_face_neighbors (this->m_mesh->m_forest, this->m_tree_id, get_element (), &neighbors, face,
+                                   dual_faces, num_neighbors, &neighids, &neigh_class,
+                                   t8_forest_is_balanced (this->m_mesh->m_forest));
+    std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
+    if (*num_neighbors > 0) {
+      /* Free allocated memory. */
+      t8_forest_get_scheme (this->m_mesh->m_forest)
+        ->element_destroy (this->get_tree_class (), *num_neighbors, neighbors);
+      T8_FREE (neighbors);
+      T8_FREE (neighids);
+    }
+    return neighbor_ids_vector;
+  }
+
+ protected:
+  //--- Private getter for internal use. ---
+  /**
+   * Getter for the leaf element of the mesh element.
+   * \return The leaf element.
+   */
+  const t8_element_t*
+  get_element () const override
+  {
+    return t8_forest_get_leaf_element_in_tree (this->m_mesh->m_forest, this->m_tree_id, this->m_element_id);
+  }
+};
+
+}  // namespace t8_mesh_handle
+#endif /* !T8_MESH_ELEMENT_HXX */
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index c3ab32a16e..ec2a059a18 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -203,10 +203,10 @@ add_t8_cpp_test( NAME t8_gtest_vector_split_serial               SOURCES t8_vect
   
 if( T8CODE_BUILD_MESH_HANDLE )
    add_t8_cpp_test( NAME t8_gtest_mesh_handle_parallel             SOURCES api/t8_mesh_handle/t8_gtest_mesh_handle.cxx )
-   add_t8_cpp_test( NAME t8_gtest_compare_handle_to_forest_serial  SOURCES api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx )
-   add_t8_cpp_test( NAME t8_gtest_ghost_parallel                   SOURCES api/t8_mesh_handle/t8_gtest_ghost.cxx )
-   add_t8_cpp_test( NAME t8_gtest_custom_competence_serial         SOURCES api/t8_mesh_handle/t8_gtest_custom_competence.cxx )
-   add_t8_cpp_test( NAME t8_gtest_cache_competence_serial          SOURCES api/t8_mesh_handle/t8_gtest_cache_competence.cxx )
+   #add_t8_cpp_test( NAME t8_gtest_compare_handle_to_forest_serial  SOURCES api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx )
+   add_t8_cpp_test( NAME t8_gtest_handle_ghost_parallel                   SOURCES api/t8_mesh_handle/t8_gtest_ghost.cxx )
+#    add_t8_cpp_test( NAME t8_gtest_custom_competence_serial         SOURCES api/t8_mesh_handle/t8_gtest_custom_competence.cxx )
+#    add_t8_cpp_test( NAME t8_gtest_cache_competence_serial          SOURCES api/t8_mesh_handle/t8_gtest_cache_competence.cxx )
 endif()
 
 copy_test_file( test_cube_unstructured_1.inp )
diff --git a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
index 85af0b1d0b..7121193f7e 100644
--- a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
@@ -21,8 +21,8 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 */
 
 /**
- * \file t8_gtest_mesh_handle.cxx
- * Tests if the mesh class of the handle works as intended for different types of predefined template parameter classes. 
+ * \file t8_gtest_ghost.cxx
+ * Tests if the ghost elements and the get_face_neighbor implementation work as intended.
  */
 
 #include <gtest/gtest.h>
@@ -31,17 +31,18 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8.h>
 
 #include <t8_mesh_handle/mesh.hxx>
-#include <t8_mesh_handle/element.hxx>
 #include <t8_mesh_handle/competences.hxx>
-#include <t8_mesh_handle/ghost.hxx>
 #include <t8_cmesh.h>
 #include <t8_cmesh/t8_cmesh_examples.h>
 #include <t8_forest/t8_forest_general.h>
+#include <t8_forest/t8_forest_balance.h>
 #include <t8_forest/t8_forest_ghost.h>
 #include <t8_schemes/t8_default/t8_default.hxx>
 
+#include <vector>
+
 /** Parametrized test fixture for the mesh handle tests. */
-class t8_mesh_handle_test: public testing::TestWithParam<std::tuple<t8_eclass_t, int>> {
+class t8_mesh_ghost_test: public testing::TestWithParam<std::tuple<t8_eclass_t, int>> {
  protected:
   void
   SetUp () override
@@ -63,19 +64,19 @@ class t8_mesh_handle_test: public testing::TestWithParam<std::tuple<t8_eclass_t,
   int level;
 };
 
-/** Test some default functionality and the iterator of \ref t8_mesh_handle::mesh class. */
-TEST_P (t8_mesh_handle_test, test_iterator)
+/** Check the implementation of ghosts and all functions accessible by ghosts. */
+TEST_P (t8_mesh_ghost_test, check_get_face_neighbors)
 {
   ASSERT_TRUE (t8_forest_is_committed (forest));
   t8_forest_ghost_print (forest);
 
-  // --- Check default functionality. ---
   t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
   EXPECT_EQ (mesh.get_local_num_ghosts (), t8_forest_get_num_ghosts (forest));
 
-  // Iterate with the iterator over all mesh elements and check some functionality.
+  // Check that functionality of mesh elements is still valid.
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
     EXPECT_FALSE (it->is_ghost_element ());
+    EXPECT_EQ (level, it->get_level ());
     auto centroid = it->get_centroid ();
     for (const auto& coordinate : centroid) {
       EXPECT_GE (1, coordinate);
@@ -90,29 +91,79 @@ TEST_P (t8_mesh_handle_test, test_iterator)
     }
   }
 
-  for (int ighost = mesh.get_local_num_elements ();
-       ighost < mesh.get_local_num_elements () + mesh.get_local_num_ghosts (); ++ighost) {
-
-    if (auto* ghost = static_cast<t8_mesh_handle::ghost_element<>*> (&mesh[ighost])) {
-      EXPECT_TRUE (ghost->is_ghost_element ());
+  // Check functions for ghost elements.
+  const t8_locidx_t num_local_elements = mesh.get_local_num_elements ();
+  const t8_locidx_t num_ghost_elements = mesh.get_local_num_ghosts ();
+  for (t8_locidx_t ighost = num_local_elements; ighost < num_local_elements + num_ghost_elements; ++ighost) {
+    EXPECT_TRUE (mesh[ighost].is_ghost_element ());
+    EXPECT_EQ (level, mesh[ighost].get_level ());
+    auto centroid = mesh[ighost].get_centroid ();
+    for (const auto& coordinate : centroid) {
+      EXPECT_GE (1, coordinate);
+      EXPECT_LE (0, coordinate);
+    }
+    auto vertex_coordinates = mesh[ighost].get_vertex_coordinates ();
+    for (int ivertex = 0; ivertex < (int) vertex_coordinates.size (); ++ivertex) {
+      for (const auto& coordinate : vertex_coordinates[ivertex]) {
+        EXPECT_GE (1, coordinate);
+        EXPECT_LE (0, coordinate);
+      }
     }
+  }
+}
+
+/** Check that the function \ref get_face_neighbors of the handle works as intended (equal results to forest).*/
+TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
+{
+  ASSERT_TRUE (t8_forest_is_committed (forest));
 
-    // Idea: virtual class element with children mesh_element and ghost_element.
-    // Alternative is to let the user choose the right function ghost or not ghost with [].
-
-    // auto centroid = it->get_centroid ();
-    // for (const auto& coordinate : centroid) {
-    //   EXPECT_GE (1, coordinate);
-    //   EXPECT_LE (0, coordinate);
-    // }
-    // auto vertex_coordinates = (*it).get_vertex_coordinates ();
-    // for (int ivertex = 0; ivertex < (int) vertex_coordinates.size (); ++ivertex) {
-    //   for (const auto& coordinate : vertex_coordinates[ivertex]) {
-    //     EXPECT_GE (1, coordinate);
-    //     EXPECT_LE (0, coordinate);
-    //   }
-    // }
+  t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
+  EXPECT_EQ (mesh.get_local_num_ghosts (), t8_forest_get_num_ghosts (forest));
+
+  const t8_scheme* scheme = t8_forest_get_scheme (forest);
+  auto mesh_iterator = mesh.cbegin ();
+  for (t8_locidx_t itree = 0; itree < t8_forest_get_num_local_trees (forest); ++itree) {
+    const t8_eclass_t tree_class = t8_forest_get_tree_class (forest, itree);
+    for (t8_locidx_t ielem = 0; ielem < t8_forest_get_tree_num_leaf_elements (forest, itree); ++ielem) {
+      // --- Compare elements. ---
+      EXPECT_EQ (mesh_iterator->get_tree_id (), itree);
+      EXPECT_EQ (mesh_iterator->get_element_id (), ielem);
+      // --- Compare neighbors. ---
+      const t8_element_t* elem = t8_forest_get_leaf_element_in_tree (forest, itree, ielem);
+      const int num_faces = scheme->element_get_num_faces (tree_class, elem);
+      EXPECT_EQ (mesh_iterator->get_num_faces (), num_faces);
+      for (int iface = 0; iface < num_faces; iface++) {
+        // --- Get neighbors from forest. ---
+        t8_element_t** neighbors;
+        int num_neighbors;
+        const int forest_is_balanced = t8_forest_is_balanced (forest);
+        t8_eclass_t neigh_eclass;
+        int* dual_faces;
+        t8_locidx_t* neigh_ids;
+        t8_forest_leaf_face_neighbors (forest, itree, elem, &neighbors, iface, &dual_faces, &num_neighbors, &neigh_ids,
+                                       &neigh_eclass, forest_is_balanced);
+        // --- Get neighbors from mesh element. ---
+        int num_neighbors_handle;
+        int* dual_faces_handle;
+        auto neighbor_ids_handle = mesh_iterator->get_face_neighbors (iface, &num_neighbors_handle, &dual_faces_handle);
+        // --- Compare results. ---
+        EXPECT_EQ ((int) neighbor_ids_handle.size (), num_neighbors_handle);
+        EXPECT_EQ (num_neighbors, num_neighbors_handle);
+        EXPECT_TRUE (std::equal (dual_faces, dual_faces + num_neighbors, dual_faces_handle));
+        EXPECT_EQ (neighbor_ids_handle, std::vector<t8_locidx_t> (neigh_ids, neigh_ids + num_neighbors));
+        // Free memory.
+        if (num_neighbors > 0) {
+          scheme->element_destroy (neigh_eclass, num_neighbors, neighbors);
+          T8_FREE (neigh_ids);
+          T8_FREE (neighbors);
+          T8_FREE (dual_faces);
+          T8_FREE (dual_faces_handle);
+        }
+      }
+      // Evolve mesh iterator.
+      mesh_iterator++;
+    }
   }
 }
 
-INSTANTIATE_TEST_SUITE_P (t8_gtest_mesh, t8_mesh_handle_test, testing::Combine (AllEclasses, testing::Range (2, 3)));
+INSTANTIATE_TEST_SUITE_P (t8_gtest_ghost, t8_mesh_ghost_test, testing::Combine (AllEclasses, testing::Range (1, 2)));
diff --git a/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx b/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
index a1793c319e..7ae19199b1 100644
--- a/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
@@ -31,7 +31,7 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8.h>
 
 #include <t8_mesh_handle/mesh.hxx>
-#include <t8_mesh_handle/element.hxx>
+#include <t8_mesh_handle/mesh_element.hxx>
 #include <t8_mesh_handle/competences.hxx>
 #include <t8_cmesh.h>
 #include <t8_cmesh/t8_cmesh_examples.h>
@@ -68,10 +68,10 @@ TEST_P (t8_mesh_handle_test, test_iterator)
 
   // --- Check default functionality. ---
   using mesh_class = t8_mesh_handle::mesh<>;
-  using mesh_element = mesh_class::mesh_element;
+  using element_class = mesh_class::abstract_element_class;
   mesh_class mesh = mesh_class (forest);
-  EXPECT_FALSE (mesh_element::has_vertex_cache ());
-  EXPECT_FALSE (mesh_element::has_centroid_cache ());
+  EXPECT_FALSE (element_class::has_vertex_cache ());
+  EXPECT_FALSE (element_class::has_centroid_cache ());
 
   // Iterate with the iterator over all mesh elements and check some functionality.
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
@@ -109,10 +109,10 @@ TEST_P (t8_mesh_handle_test, test_competences)
 
   // --- Version with cached vertex coordinates. ---
   using mesh_class_vertex = t8_mesh_handle::mesh<t8_mesh_handle::cache_vertex_coordinates>;
-  using mesh_element_vertex = mesh_class_vertex::mesh_element;
+  using element_class_vertex = mesh_class_vertex::abstract_element_class;
   mesh_class_vertex mesh_vertex = mesh_class_vertex (forest);
-  EXPECT_TRUE (mesh_element_vertex::has_vertex_cache ());
-  EXPECT_FALSE (mesh_element_vertex::has_centroid_cache ());
+  EXPECT_TRUE (element_class_vertex::has_vertex_cache ());
+  EXPECT_FALSE (element_class_vertex::has_centroid_cache ());
 
   // Iterate with the iterator over all mesh elements and check functionality.
   for (auto it = mesh_vertex.begin (); it != mesh_vertex.end (); ++it) {
@@ -145,10 +145,10 @@ TEST_P (t8_mesh_handle_test, test_competences)
 
   // --- Version with cached centroid variable. ---
   using mesh_class_centroid = t8_mesh_handle::mesh<t8_mesh_handle::cache_centroid>;
-  using mesh_element_centroid = mesh_class_centroid::mesh_element;
+  using element_class_centroid = mesh_class_centroid::abstract_element_class;
   mesh_class_centroid mesh_centroid = mesh_class_centroid (forest);
-  EXPECT_FALSE (mesh_element_centroid::has_vertex_cache ());
-  EXPECT_TRUE (mesh_element_centroid::has_centroid_cache ());
+  EXPECT_FALSE (element_class_centroid::has_vertex_cache ());
+  EXPECT_TRUE (element_class_centroid::has_centroid_cache ());
 
   // Iterate with the iterator over all mesh elements.
   for (auto it = mesh_centroid.begin (); it != mesh_centroid.end (); ++it) {
@@ -174,10 +174,10 @@ TEST_P (t8_mesh_handle_test, test_2_competences)
 
   // --- Use competences to cache level and centroid. ---
   using mesh_class = t8_mesh_handle::mesh<t8_mesh_handle::cache_vertex_coordinates, t8_mesh_handle::cache_centroid>;
-  using mesh_element = mesh_class::mesh_element;
+  using element_class = mesh_class::abstract_element_class;
   mesh_class mesh = mesh_class (forest);
-  EXPECT_TRUE (mesh_element::has_vertex_cache ());
-  EXPECT_TRUE (mesh_element::has_centroid_cache ());
+  EXPECT_TRUE (element_class::has_vertex_cache ());
+  EXPECT_TRUE (element_class::has_centroid_cache ());
 
   // Iterate with the iterator over all mesh elements.
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {

From 719f831139b6d5348baaad982aae33e629ff64ad Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Fri, 31 Oct 2025 12:12:12 +0100
Subject: [PATCH 06/24] adapt remaining tests

---
 test/CMakeLists.txt                                 | 10 +++++-----
 .../t8_mesh_handle/t8_gtest_cache_competence.cxx    | 13 ++++++-------
 .../t8_gtest_compare_handle_to_forest.cxx           |  4 ----
 .../t8_mesh_handle/t8_gtest_custom_competence.cxx   |  1 -
 test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx    |  1 -
 5 files changed, 11 insertions(+), 18 deletions(-)

diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index ec2a059a18..11e5d6786e 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -202,11 +202,11 @@ endif()
 add_t8_cpp_test( NAME t8_gtest_vector_split_serial               SOURCES t8_vector_helper/t8_gtest_vector_split.cxx )
   
 if( T8CODE_BUILD_MESH_HANDLE )
-   add_t8_cpp_test( NAME t8_gtest_mesh_handle_parallel             SOURCES api/t8_mesh_handle/t8_gtest_mesh_handle.cxx )
-   #add_t8_cpp_test( NAME t8_gtest_compare_handle_to_forest_serial  SOURCES api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx )
-   add_t8_cpp_test( NAME t8_gtest_handle_ghost_parallel                   SOURCES api/t8_mesh_handle/t8_gtest_ghost.cxx )
-#    add_t8_cpp_test( NAME t8_gtest_custom_competence_serial         SOURCES api/t8_mesh_handle/t8_gtest_custom_competence.cxx )
-#    add_t8_cpp_test( NAME t8_gtest_cache_competence_serial          SOURCES api/t8_mesh_handle/t8_gtest_cache_competence.cxx )
+   add_t8_cpp_test( NAME t8_gtest_mesh_handle_parallel              SOURCES api/t8_mesh_handle/t8_gtest_mesh_handle.cxx )
+   add_t8_cpp_test( NAME t8_gtest_compare_handle_to_forest_serial   SOURCES api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx )
+   add_t8_cpp_test( NAME t8_gtest_handle_ghost_parallel             SOURCES api/t8_mesh_handle/t8_gtest_ghost.cxx )
+   add_t8_cpp_test( NAME t8_gtest_custom_competence_serial          SOURCES api/t8_mesh_handle/t8_gtest_custom_competence.cxx )
+   add_t8_cpp_test( NAME t8_gtest_cache_competence_serial           SOURCES api/t8_mesh_handle/t8_gtest_cache_competence.cxx )
 endif()
 
 copy_test_file( test_cube_unstructured_1.inp )
diff --git a/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx b/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
index e54d018945..9f6a754fa6 100644
--- a/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_cache_competence.cxx
@@ -30,7 +30,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8.h>
 
 #include <t8_mesh_handle/mesh.hxx>
-#include <t8_mesh_handle/element.hxx>
 #include <t8_mesh_handle/competences.hxx>
 #include <t8_cmesh.h>
 #include <t8_cmesh/t8_cmesh_examples.h>
@@ -100,10 +99,10 @@ TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
   ASSERT_EQ (true, t8_forest_is_committed (forest));
 
   using mesh_class = t8_mesh_handle::mesh<cache_vertex_coordinates_overwrite>;
-  using mesh_element = mesh_class::mesh_element;
+  using element_class = mesh_class::abstract_element_class;
   mesh_class mesh = mesh_class (forest);
-  EXPECT_TRUE (mesh_element::has_vertex_cache ());
-  EXPECT_FALSE (mesh_element::has_centroid_cache ());
+  EXPECT_TRUE (element_class::has_vertex_cache ());
+  EXPECT_FALSE (element_class::has_centroid_cache ());
 
   std::vector<t8_3D_point> unrealistic_vertex = { t8_3D_point ({ 41, 42, 43 }), t8_3D_point ({ 99, 100, 101 }) };
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
@@ -135,10 +134,10 @@ TEST_F (t8_gtest_cache_competence, cache_centroid)
   ASSERT_EQ (true, t8_forest_is_committed (forest));
 
   using mesh_class = t8_mesh_handle::mesh<cache_centroid_overwrite>;
-  using mesh_element = mesh_class::mesh_element;
+  using element_class = mesh_class::abstract_element_class;
   mesh_class mesh = mesh_class (forest);
-  EXPECT_FALSE (mesh_element::has_vertex_cache ());
-  EXPECT_TRUE (mesh_element::has_centroid_cache ());
+  EXPECT_FALSE (element_class::has_vertex_cache ());
+  EXPECT_TRUE (element_class::has_centroid_cache ());
 
   t8_3D_point unrealistic_centroid ({ 999, 1000, 998 });
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
diff --git a/test/api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx b/test/api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx
index 8b1681e26c..5521a56023 100644
--- a/test/api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_compare_handle_to_forest.cxx
@@ -26,13 +26,9 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
  */
 
 #include <gtest/gtest.h>
-#include <test/t8_gtest_schemes.hxx>
-#include <test/t8_gtest_macros.hxx>
 #include <t8.h>
 
 #include <t8_mesh_handle/mesh.hxx>
-#include <t8_mesh_handle/element.hxx>
-#include <t8_mesh_handle/competences.hxx>
 #include <t8_cmesh.h>
 #include <t8_cmesh/t8_cmesh_examples.h>
 #include <t8_forest/t8_forest_general.h>
diff --git a/test/api/t8_mesh_handle/t8_gtest_custom_competence.cxx b/test/api/t8_mesh_handle/t8_gtest_custom_competence.cxx
index b207048a17..103cefd94e 100644
--- a/test/api/t8_mesh_handle/t8_gtest_custom_competence.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_custom_competence.cxx
@@ -30,7 +30,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8.h>
 
 #include <t8_mesh_handle/mesh.hxx>
-#include <t8_mesh_handle/element.hxx>
 #include <t8_mesh_handle/competences.hxx>
 #include <t8_cmesh.h>
 #include <t8_cmesh/t8_cmesh_examples.h>
diff --git a/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx b/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
index 7ae19199b1..3f991293e1 100644
--- a/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_mesh_handle.cxx
@@ -31,7 +31,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8.h>
 
 #include <t8_mesh_handle/mesh.hxx>
-#include <t8_mesh_handle/mesh_element.hxx>
 #include <t8_mesh_handle/competences.hxx>
 #include <t8_cmesh.h>
 #include <t8_cmesh/t8_cmesh_examples.h>

From db7bcf63e2ca56fb0cd8cdafcce408fc41a5223b Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Fri, 31 Oct 2025 13:30:41 +0100
Subject: [PATCH 07/24] documentation

---
 api/t8_mesh_handle/README.md            |  1 +
 api/t8_mesh_handle/abstract_element.hxx | 54 +++++++++++++-----------
 api/t8_mesh_handle/ghost_element.hxx    | 32 ++++++++++----
 api/t8_mesh_handle/mesh.hxx             |  3 +-
 api/t8_mesh_handle/mesh_element.hxx     | 55 ++++++++++---------------
 5 files changed, 78 insertions(+), 67 deletions(-)

diff --git a/api/t8_mesh_handle/README.md b/api/t8_mesh_handle/README.md
index 99920b73f5..2b03ed8ddf 100644
--- a/api/t8_mesh_handle/README.md
+++ b/api/t8_mesh_handle/README.md
@@ -9,3 +9,4 @@ If you want to use the handle, note that is has its own library. Turn the option
 The [mesh.hxx](mesh.hxx) defines the mesh class of the handle.
 The [element.hxx](element.hxx) defines the elements used in the mesh class.
 The [competences.hxx](competences.hxx) defines additional competences/functionality of an element that we want to access beyond the default functions.
+TODO
\ No newline at end of file
diff --git a/api/t8_mesh_handle/abstract_element.hxx b/api/t8_mesh_handle/abstract_element.hxx
index 8e0a654f85..9e22519c5d 100644
--- a/api/t8_mesh_handle/abstract_element.hxx
+++ b/api/t8_mesh_handle/abstract_element.hxx
@@ -20,8 +20,8 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** \file element.hxx
- * Definition of the elements used in the mesh class.
+/** \file abstract_element.hxx
+ * Common interface of the mesh elements and the ghost elements of the mesh handle.
  */
 
 #ifndef T8_ABSTRACT_ELEMENT_HXX
@@ -46,14 +46,15 @@ template <template <typename> class... TCompetence>
 class mesh;
 
 /** 
- * Class for the elements of the mesh handle. 
- * The element without specified template parameters provides default implementations for basic functionality 
+ * Common interface of the mesh elements and the ghost elements of the mesh handle.
+ * An element without specified template parameters provides default implementations for basic functionality 
  * as accessing the refinement level or the centroid. With this implementation, the functionality is calculated each time
  * the function is called. 
  * Use the competences defined in competences.hxx as template parameter to cache the functionality instead of 
  * recalculating in every function call.
  * To add functionality to the element, you can also simply write your own competence class and give it as a template parameter.
  * You can access the functions implemented in your competence via the element. 
+ * Please note that the competence should be valid for both, mesh elements and ghost elements.
  *
  * The inheritance pattern is inspired by the \ref T8Type class (which also uses the CRTP).
  * We decided to use this structure 1.) to be able to add new functionality easily and 
@@ -70,7 +71,8 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   friend mesh_class;
 
   /**
-   * Constructor for an element of a mesh.
+   * Protected constructor for an element of a mesh. 
+   * This constructor of the abstract class should only be called by child classes.
    * \param [in] mesh           Pointer to the mesh the element should belong to.
    * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
    * \param [in] element_id     The element id of the element in the forest defining the mesh.
@@ -92,7 +94,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
     return requires (T<SelfType>& competence) { competence.vertex_cache_filled (); };
   }
   /* This variable is true if any of the given competences \ref TCompetence implements 
-  a function vertex_cache_filled */
+  a function vertex_cache_filled. */
   static constexpr bool vertex_cache_exists = (false || ... || vertex_cache_defined<TCompetence> ());
 
   /** Helper function to check if class T implements the function centroid_cache_filled.
@@ -131,18 +133,11 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
     return centroid_cache_exists;
   }
 
-  /**
-   * TODO
-   */
-  virtual constexpr bool
-  is_ghost_element ()
-    = 0;
-
   // --- Functionality of the element. In each function, it is checked if a cached version exists (and is used then). ---
   /**
-   * Getter for the refinement level of the mesh element.
+   * Getter for the refinement level of the element.
    * For this easily accessible variable, it makes no sense to provide a cached version.
-   * \return Refinement level of the mesh element.
+   * \return Refinement level of the element.
    */
   t8_element_level
   get_level () const
@@ -153,9 +148,9 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   }
 
   /**
-   * Getter for the number of faces of the mesh element.
+   * Getter for the number of faces of the element.
    * For this easily accessible variable, it makes no sense to provide a cached version.
-   * \return Number of faces of the mesh element.
+   * \return Number of faces of the element.
    */
   int
   get_num_faces () const
@@ -164,7 +159,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   }
 
   /**
-   * Getter for the vertex coordinates of the mesh element.
+   * Getter for the vertex coordinates of the element.
    * This function uses or sets the cached version defined in TCompetence if available and calculates if not.
    * \return Vector with one coordinate array for each vertex of the element.
    */
@@ -197,7 +192,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   }
 
   /**
-   * Getter for the center of mass of the mesh element.
+   * Getter for the center of mass of the element.
    * This function uses the cached version defined in TCompetence if available and calculates if not.
    * \return Coordinates of the center.
    */
@@ -221,7 +216,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
 
   //--- Getter for the member variables. ---
   /**
-   * Getter for the tree id of the mesh element.
+   * Getter for the tree id of the element.
    * \return The element's tree id.
    */
   t8_locidx_t
@@ -231,8 +226,8 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   }
 
   /**
-   * Getter for the element id of the mesh element.
-   * \return The element id of the mesh element.
+   * Getter for the element id of the element.
+   * \return The element id of the element.
    */
   t8_locidx_t
   get_element_id () const
@@ -241,7 +236,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   }
 
   /**
-   * Getter for the mesh to which the mesh element is belonging.
+   * Getter for the mesh to which the element is belonging.
    * \return Reference to the mesh.
    */
   const mesh<TCompetence...>*
@@ -250,10 +245,19 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
     return m_mesh;
   }
 
+  /**
+   * Virtual function to check if the element is a ghost element.
+   * \return true if the element is a ghost element, false otherwise.
+   */
+  virtual constexpr bool
+  is_ghost_element ()
+    = 0;
+
  protected:
   //--- Private getter for internal use. ---
   /**
-   * Getter for the leaf element of the mesh element.
+   * Getter for the leaf element of the element.
+   * Has to be implemented differently for mesh elements and ghost elements.
    * \return The leaf element.
    */
   virtual const t8_element_t*
@@ -261,7 +265,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
     = 0;
 
   /**
-   * Getter for the eclass of the mesh element.
+   * Getter for the eclass of the element.
    * \return The element's eclass.
    */
   t8_eclass_t
diff --git a/api/t8_mesh_handle/ghost_element.hxx b/api/t8_mesh_handle/ghost_element.hxx
index 1b776461f9..d36e03011a 100644
--- a/api/t8_mesh_handle/ghost_element.hxx
+++ b/api/t8_mesh_handle/ghost_element.hxx
@@ -20,8 +20,8 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** \file ghost.hxx
- * TODO
+/** \file ghost_element.hxx
+ * Implementation of the ghost element class of the mesh handle.
  */
 
 #ifndef T8_GHOST_ELEMENT_HXX
@@ -39,12 +39,27 @@ namespace t8_mesh_handle
 template <template <typename> class... TCompetence>
 class mesh;
 
+/** 
+ * Class for the ghost elements of the mesh handle. 
+ * This class is a child class of the abstract element class and implements the functionality specific to ghost elements.
+ * See \ref abstract_element for more information, especially on the template parameter.
+ *
+ * \tparam TCompetence The competences you want to add to the default functionality of the element.
+ */
 template <template <typename> class... TCompetence>
 class ghost_element: public abstract_element<TCompetence...> {
   using Base = abstract_element<TCompetence...>;
   using mesh_class = mesh<TCompetence...>;
   friend mesh_class;
 
+  /**
+   * Constructor for a ghost element. This constructor can only be called by the friend mesh class as
+   * the user should use the mesh class to construct ghost elements.
+   * \param [in] mesh             Pointer to the mesh the ghost element should belong to.
+   * \param [in] tree_id          The tree id of the element (normally the number of local trees + local ghost tree id).
+   * \param [in] lghost_tree_id   The ghost tree id of the element in the forest defining the mesh.
+   * \param [in] element_id       The element id of the element in the forest defining the mesh.
+   */
   ghost_element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t lghost_tree_id, t8_locidx_t element_id)
     : Base (mesh, tree_id, element_id), m_lghost_tree_id (lghost_tree_id)
   {
@@ -52,7 +67,8 @@ class ghost_element: public abstract_element<TCompetence...> {
 
  public:
   /**
-   * TODO
+   * Implementation of the function to check if the element is a ghost element.
+   * \return Always true for the ghost element class.
    */
   constexpr bool
   is_ghost_element () override
@@ -60,13 +76,13 @@ class ghost_element: public abstract_element<TCompetence...> {
     return true;
   }
 
-  // /** It is not possible for ghosts to compute their neighbors. */
-  // std::vector<t8_locidx_t>
-  // get_face_neighbors (int face, int* num_neighbors, int* dual_faces[]) =delete;
-
  private:
+  /**
+   * Implementation of the getter for the leaf element of the ghost element.
+   * \return The leaf element.
+   */
   const t8_element_t*
-  get_element () const
+  get_element () const override
   {
     return t8_forest_ghost_get_leaf_element (this->m_mesh->m_forest, m_lghost_tree_id, this->m_element_id);
   }
diff --git a/api/t8_mesh_handle/mesh.hxx b/api/t8_mesh_handle/mesh.hxx
index 316b61017a..f2e76f55a6 100644
--- a/api/t8_mesh_handle/mesh.hxx
+++ b/api/t8_mesh_handle/mesh.hxx
@@ -45,6 +45,7 @@ namespace t8_mesh_handle
  * \tparam TCompetence TODO The element class that should be used for the elements in the mesh class. 
  *                                  This template parameter defines which element functionality is available 
  *                                  and if it is cached or calculated.
+ TODO: also update some functions
  */
 template <template <typename> class... TCompetence>
 class mesh {
@@ -52,7 +53,7 @@ class mesh {
   using abstract_element_class = abstract_element<TCompetence...>;
   using mesh_element_class = mesh_element<TCompetence...>;
   using ghost_element_class = ghost_element<TCompetence...>;
-  // Declare mesh element as friend such that private members (e.g. the forest) can be accessed.
+  // Declare all element classes as friend such that private members (e.g. the forest) can be accessed.
   friend abstract_element_class;
   friend mesh_element_class;
   friend ghost_element_class;
diff --git a/api/t8_mesh_handle/mesh_element.hxx b/api/t8_mesh_handle/mesh_element.hxx
index c8910886a4..3652e8b8ed 100644
--- a/api/t8_mesh_handle/mesh_element.hxx
+++ b/api/t8_mesh_handle/mesh_element.hxx
@@ -20,15 +20,15 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** \file element.hxx TODO
- * Definition of the elements used in the mesh class.
+/** \file mesh_element.hxx
+ * Implementation of the mesh element class of the mesh handle.
  */
 
 #ifndef T8_MESH_ELEMENT_HXX
 #define T8_MESH_ELEMENT_HXX
 
-#include <t8_mesh_handle/abstract_element.hxx>
 #include <t8.h>
+#include <t8_mesh_handle/abstract_element.hxx>
 #include <t8_element.h>
 #include <t8_eclass.h>
 #include <t8_forest/t8_forest_general.h>
@@ -47,19 +47,9 @@ template <template <typename> class... TCompetence>
 class mesh;
 
 /** 
- * Class for the elements of the mesh handle. 
- * The element without specified template parameters provides default implementations for basic functionality 
- * as accessing the refinement level or the centroid. With this implementation, the functionality is calculated each time
- * the function is called. 
- * Use the competences defined in competences.hxx as template parameter to cache the functionality instead of 
- * recalculating in every function call.
- * To add functionality to the element, you can also simply write your own competence class and give it as a template parameter.
- * You can access the functions implemented in your competence via the element. 
- *
- * The inheritance pattern is inspired by the \ref T8Type class (which also uses the CRTP).
- * We decided to use this structure 1.) to be able to add new functionality easily and 
- *    2.) for the cached options to keep the number of class member variables of the default to a minimum to save memory.
- * The choice between calculate and cache is a tradeoff between runtime and memory usage. 
+ * Class for the mesh elements of the mesh handle. 
+ * This class is a child class of the abstract element class and implements the functionality specific to mesh elements 
+ * (meaning non-ghost elements). See \ref abstract_element for more information, especially on the template parameter.
  *
  * \tparam TCompetence The competences you want to add to the default functionality of the element.
  */
@@ -71,8 +61,9 @@ class mesh_element: public abstract_element<TCompetence...> {
   friend mesh_class;
 
   /**
-   * Constructor for an element of a mesh.
-   * \param [in] mesh           Pointer to the mesh the element should belong to.
+   * Constructor for a mesh element. This constructor can only be called by the friend mesh class as
+   * the user should use the mesh class to construct the elements.
+   * \param [in] mesh           Pointer to the mesh the mesh element should belong to.
    * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
    * \param [in] element_id     The element id of the element in the forest defining the mesh.
    */
@@ -82,20 +73,8 @@ class mesh_element: public abstract_element<TCompetence...> {
   }
 
  public:
-  // --- Functions to check if caches exist. ---
-
-  /**
-   * TODO
-   */
-  constexpr bool
-  is_ghost_element () override
-  {
-    return false;
-  }
-
-  // --- Functionality of the element. In each function, it is checked if a cached version exists (and is used then). ---
-
-  /** TODO*/
+  // --- Functionality special to the mesh element. ---
+  /** TODO Not possible for ghosts to calculate, see docu of t8_forest... and dont forget to state the necessary free calls. */
   std::vector<t8_locidx_t>
   get_face_neighbors (int face, int* num_neighbors, int* dual_faces[]) const
   {
@@ -118,10 +97,20 @@ class mesh_element: public abstract_element<TCompetence...> {
     return neighbor_ids_vector;
   }
 
+  /**
+   * Implementation of the function to check if the element is a ghost element.
+   * \return Always false for the mesh element class.
+   */
+  constexpr bool
+  is_ghost_element () override
+  {
+    return false;
+  }
+
  protected:
   //--- Private getter for internal use. ---
   /**
-   * Getter for the leaf element of the mesh element.
+   * Implementation of the getter for the leaf element of the mesh element.
    * \return The leaf element.
    */
   const t8_element_t*

From 3ed16f4e79015c59f9dbbd554207831ffd3499f3 Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Mon, 3 Nov 2025 10:16:22 +0100
Subject: [PATCH 08/24] documentation

---
 api/t8_mesh_handle/README.md        | 10 ++++++----
 api/t8_mesh_handle/mesh.hxx         | 16 +++++++++-------
 api/t8_mesh_handle/mesh_element.hxx | 15 ++++++++++++++-
 3 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/api/t8_mesh_handle/README.md b/api/t8_mesh_handle/README.md
index 2b03ed8ddf..76516d5102 100644
--- a/api/t8_mesh_handle/README.md
+++ b/api/t8_mesh_handle/README.md
@@ -6,7 +6,9 @@ Some application codes are designed for unstructured or uniform meshes and canno
 
 If you want to use the handle, note that is has its own library. Turn the option `T8CODE_BUILD_MESH_HANDLE` to `ON` and link against the target `T8_MESH_HANDLE` please.
 
-The [mesh.hxx](mesh.hxx) defines the mesh class of the handle.
-The [element.hxx](element.hxx) defines the elements used in the mesh class.
-The [competences.hxx](competences.hxx) defines additional competences/functionality of an element that we want to access beyond the default functions.
-TODO
\ No newline at end of file
+The folder's most important files are: 
+The [mesh.hxx](mesh.hxx) defines the mesh class of the handle. This is the central file of the mesh handle. 
+The [abstract_element.hxx](abstract_element.hxx) defines the common interface of the mesh elements and the ghost elements of the mesh handle.
+The [mesh_element.hxx](mesh_element.hxx) implements a class for the mesh elements of the mesh handle (so non-ghost elements).
+The [ghost_element.hxx](ghost_element.hxx) implements the class for the ghost elements of the mesh handle.
+The [competences.hxx](competences.hxx) defines additional competences/functionality of an element that we want to access beyond the default functions.
\ No newline at end of file
diff --git a/api/t8_mesh_handle/mesh.hxx b/api/t8_mesh_handle/mesh.hxx
index f2e76f55a6..1aaf4070aa 100644
--- a/api/t8_mesh_handle/mesh.hxx
+++ b/api/t8_mesh_handle/mesh.hxx
@@ -42,10 +42,8 @@ namespace t8_mesh_handle
 
 /**
  * Wrapper for a forest that enables it to be handled as a simple mesh object.
- * \tparam TCompetence TODO The element class that should be used for the elements in the mesh class. 
- *                                  This template parameter defines which element functionality is available 
- *                                  and if it is cached or calculated.
- TODO: also update some functions
+ * \tparam TCompetence The competences you want to add to the default functionality of the mesh.
+ *         \see abstract_element for more details on the choice of the template parameter.   
  */
 template <template <typename> class... TCompetence>
 class mesh {
@@ -82,7 +80,7 @@ class mesh {
 
   /**
    * Getter for the number of local ghost elements.
-   * \return Number of local ghost elements in the unstructured mesh.
+   * \return Number of local ghost elements in the mesh.
    */
   t8_locidx_t
   get_local_num_ghosts () const
@@ -102,6 +100,7 @@ class mesh {
 
   /**
    * Returns an iterator to a mesh element following the last (local) element of the mesh.
+   * The iterator only refers to local mesh element and excludes ghost elements.
    * \return Iterator to the mesh element following the last (local) element of the mesh.
    */
   mesh_iterator
@@ -131,9 +130,11 @@ class mesh {
   }
 
   /**
-   * Getter for a mesh element given its local index.
+   * Getter for an element given its local index. This could be a (local) mesh element or a ghost element. 
+   * The indices 0, 1, ... num_local_el - 1 refer to local mesh elements and 
+   *    num_local_el , ... , num_local_el + num_ghosts - 1 refer to ghost elements.
    * \param [in] local_index The local index of the element to access.
-   * \return Reference to the mesh element.
+   * \return Reference to the element.
    */
   abstract_element_class&
   operator[] (t8_locidx_t local_index)
@@ -195,6 +196,7 @@ class mesh {
   void
   update_ghost_elements ()
   {
+    // Clear the ghost vector if already created.
     if (!m_ghosts.empty ()) {
       m_ghosts.clear ();
     }
diff --git a/api/t8_mesh_handle/mesh_element.hxx b/api/t8_mesh_handle/mesh_element.hxx
index 3652e8b8ed..638719de99 100644
--- a/api/t8_mesh_handle/mesh_element.hxx
+++ b/api/t8_mesh_handle/mesh_element.hxx
@@ -74,7 +74,20 @@ class mesh_element: public abstract_element<TCompetence...> {
 
  public:
   // --- Functionality special to the mesh element. ---
-  /** TODO Not possible for ghosts to calculate, see docu of t8_forest... and dont forget to state the necessary free calls. */
+  /** Getter for the face neighbors of the mesh element at given face.
+   * For ghost elements, the functionality to calculate face neighbors is not provided.
+   * \param [in]  face          The index of the face across which the face neighbors are searched.
+   * \param [out] num_neighbors On output the number of neighbor elements.
+   * \param [out] dual_faces    On output the face id's of the neighboring elements' faces.
+   * \return Vector of length \ref num_neighbors with the element indices of the face neighbors.
+   *         0, 1, ... num_local_el - 1 for local mesh elements and 
+   *         num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
+   * \note Important! This routine allocates memory for \ref dual_faces which must be freed. Do it like this:
+   *
+   *   if (num_neighbors > 0) {
+   *     T8_FREE (dual_faces);
+   *   }
+   */
   std::vector<t8_locidx_t>
   get_face_neighbors (int face, int* num_neighbors, int* dual_faces[]) const
   {

From f27d7efa002a97bf186926bbef7a29c5b4f0215e Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Tue, 4 Nov 2025 12:01:15 +0100
Subject: [PATCH 09/24] add cache for neighbors

---
 api/t8_mesh_handle/abstract_element.hxx    |  2 +-
 api/t8_mesh_handle/competences.hxx         | 30 +++++++++++++
 api/t8_mesh_handle/mesh_element.hxx        | 50 ++++++++++++++++++----
 test/api/t8_mesh_handle/t8_gtest_ghost.cxx | 10 ++---
 4 files changed, 78 insertions(+), 14 deletions(-)

diff --git a/api/t8_mesh_handle/abstract_element.hxx b/api/t8_mesh_handle/abstract_element.hxx
index 9e22519c5d..c8c5392309 100644
--- a/api/t8_mesh_handle/abstract_element.hxx
+++ b/api/t8_mesh_handle/abstract_element.hxx
@@ -160,7 +160,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
 
   /**
    * Getter for the vertex coordinates of the element.
-   * This function uses or sets the cached version defined in TCompetence if available and calculates if not.
+   * This function uses the cached version defined in TCompetence if available and calculates if not.
    * \return Vector with one coordinate array for each vertex of the element.
    */
   std::vector<t8_3D_point>
diff --git a/api/t8_mesh_handle/competences.hxx b/api/t8_mesh_handle/competences.hxx
index fc44ff1871..69c56f448e 100644
--- a/api/t8_mesh_handle/competences.hxx
+++ b/api/t8_mesh_handle/competences.hxx
@@ -95,5 +95,35 @@ struct cache_centroid: t8_crtp_operator<TUnderlying, cache_centroid>
     m_centroid; /**< Cache for the coordinates of the centroid. Use optional to allow no value if cache is not filled. */
 };
 
+/**
+ * TODO
+ * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
+ */
+template <typename TUnderlying>
+struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
+{
+ public:
+  /**
+   * Function that checks if the cache for the centroid has been filled.
+   * \return true if the cache for the centroid has been filled, false otherwise.
+   */
+  bool
+  neighbor_cache_filled (int face) const
+  {
+    if (!m_neighbor_indices.empty ())
+      return false;
+    if ((int) m_neighbor_indices.size () <= face)
+      return false;
+    return !m_neighbor_indices[face].empty ();
+  }
+
+ protected:
+  mutable std::vector<std::vector<t8_locidx_t>>
+    m_neighbor_indices; /**< Element indices of the neighbors at each face. The length of the vectors is stored in \ref m_num_neighbors. */
+  mutable std::vector<int> m_num_neighbors; /**< Vector with the numbers of neighbor elements at each face. */
+  mutable std::vector<std::vector<int>>
+    m_dual_faces; /**< Face id's of the neighboring elements' faces for each face. */
+};
+
 }  // namespace t8_mesh_handle
 #endif /* !T8_COMPETENCES_HXX */
diff --git a/api/t8_mesh_handle/mesh_element.hxx b/api/t8_mesh_handle/mesh_element.hxx
index 638719de99..53471bb8f4 100644
--- a/api/t8_mesh_handle/mesh_element.hxx
+++ b/api/t8_mesh_handle/mesh_element.hxx
@@ -60,6 +60,21 @@ class mesh_element: public abstract_element<TCompetence...> {
   using mesh_class = Base::mesh_class;
   friend mesh_class;
 
+  // --- Variables to check which functionality is defined in TCompetence. ---
+  /** Helper function to check if class T implements the function neighbor_cache_filled.
+   * \tparam T The competence to be checked.
+   * \return true if T implements the function, false if not.
+   */
+  template <template <typename> class T>
+  static constexpr bool
+  neighbor_cache_defined ()
+  {
+    return requires (T<SelfType>& competence) { competence.neighbor_cache_filled (0); };
+  }
+  /* This variable is true if any of the given competences \ref TCompetence implements 
+  a function neighbor_cache_filled. */
+  static constexpr bool neighbor_cache_exists = (false || ... || neighbor_cache_defined<TCompetence> ());
+
   /**
    * Constructor for a mesh element. This constructor can only be called by the friend mesh class as
    * the user should use the mesh class to construct the elements.
@@ -70,43 +85,62 @@ class mesh_element: public abstract_element<TCompetence...> {
   mesh_element (mesh<TCompetence...>* mesh, t8_locidx_t tree_id, t8_locidx_t element_id)
     : Base (mesh, tree_id, element_id)
   {
+    if constexpr (neighbor_cache_exists) {
+      // Resize neighbor caches for clean access to the caches.
+      const int num_faces = this->get_num_faces ();
+      this->m_num_neighbors.resize (num_faces);
+      this->m_dual_faces.resize (num_faces);
+      this->m_neighbor_indices.resize (num_faces);
+    }
   }
 
  public:
   // --- Functionality special to the mesh element. ---
   /** Getter for the face neighbors of the mesh element at given face.
-   * For ghost elements, the functionality to calculate face neighbors is not provided.
+   * For ghost elements, the functionality to calculate face neighbors is currently not provided.
+   * This function uses the cached version defined in TCompetence if available and calculates if not.
    * \param [in]  face          The index of the face across which the face neighbors are searched.
    * \param [out] num_neighbors On output the number of neighbor elements.
    * \param [out] dual_faces    On output the face id's of the neighboring elements' faces.
    * \return Vector of length \ref num_neighbors with the element indices of the face neighbors.
    *         0, 1, ... num_local_el - 1 for local mesh elements and 
    *         num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
-   * \note Important! This routine allocates memory for \ref dual_faces which must be freed. Do it like this:
-   *
-   *   if (num_neighbors > 0) {
-   *     T8_FREE (dual_faces);
-   *   }
    */
   std::vector<t8_locidx_t>
-  get_face_neighbors (int face, int* num_neighbors, int* dual_faces[]) const
+  get_face_neighbors (int face, int* num_neighbors, std::vector<int>* dual_faces) const
   {
+    if constexpr (neighbor_cache_exists) {
+      if (this->neighbor_cache_filled (face)) {
+        num_neighbors = &this->m_num_neighbors[face];
+        dual_faces = &(this->m_dual_faces[face]);
+        return this->m_neighbor_indices[face];
+      }
+    }
     std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
     t8_element_t** neighbors; /*< Neighboring elements. */
+    int* dual_faces_internal; /**< The face indices of the neighbor elements. */
     t8_locidx_t* neighids;    /*< Neighboring elements ids. */
     t8_eclass_t neigh_class;  /*< Neighboring elements tree class. */
 
     t8_forest_leaf_face_neighbors (this->m_mesh->m_forest, this->m_tree_id, get_element (), &neighbors, face,
-                                   dual_faces, num_neighbors, &neighids, &neigh_class,
+                                   &dual_faces_internal, num_neighbors, &neighids, &neigh_class,
                                    t8_forest_is_balanced (this->m_mesh->m_forest));
+    dual_faces->assign (dual_faces_internal, dual_faces_internal + *num_neighbors);
     std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
     if (*num_neighbors > 0) {
       /* Free allocated memory. */
       t8_forest_get_scheme (this->m_mesh->m_forest)
         ->element_destroy (this->get_tree_class (), *num_neighbors, neighbors);
       T8_FREE (neighbors);
+      T8_FREE (dual_faces_internal);
       T8_FREE (neighids);
     }
+    if constexpr (neighbor_cache_exists) {
+      this->m_num_neighbors[face] = *num_neighbors;
+      this->m_dual_faces[face] = *dual_faces;
+      this->m_neighbor_indices[face] = std::move (neighbor_ids_vector);
+      return this->m_neighbor_indices[face];
+    }
     return neighbor_ids_vector;
   }
 
diff --git a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
index 7121193f7e..1a3ecc42e8 100644
--- a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
@@ -65,7 +65,7 @@ class t8_mesh_ghost_test: public testing::TestWithParam<std::tuple<t8_eclass_t,
 };
 
 /** Check the implementation of ghosts and all functions accessible by ghosts. */
-TEST_P (t8_mesh_ghost_test, check_get_face_neighbors)
+TEST_P (t8_mesh_ghost_test, check_ghosts)
 {
   ASSERT_TRUE (t8_forest_is_committed (forest));
   t8_forest_ghost_print (forest);
@@ -117,7 +117,8 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
 {
   ASSERT_TRUE (t8_forest_is_committed (forest));
 
-  t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
+  t8_mesh_handle::mesh<t8_mesh_handle::cache_neighbors> mesh
+    = t8_mesh_handle::mesh<t8_mesh_handle::cache_neighbors> (forest);
   EXPECT_EQ (mesh.get_local_num_ghosts (), t8_forest_get_num_ghosts (forest));
 
   const t8_scheme* scheme = t8_forest_get_scheme (forest);
@@ -144,12 +145,12 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
                                        &neigh_eclass, forest_is_balanced);
         // --- Get neighbors from mesh element. ---
         int num_neighbors_handle;
-        int* dual_faces_handle;
+        std::vector<int> dual_faces_handle;
         auto neighbor_ids_handle = mesh_iterator->get_face_neighbors (iface, &num_neighbors_handle, &dual_faces_handle);
         // --- Compare results. ---
         EXPECT_EQ ((int) neighbor_ids_handle.size (), num_neighbors_handle);
         EXPECT_EQ (num_neighbors, num_neighbors_handle);
-        EXPECT_TRUE (std::equal (dual_faces, dual_faces + num_neighbors, dual_faces_handle));
+        EXPECT_EQ (dual_faces_handle, std::vector<int> (dual_faces, dual_faces + num_neighbors));
         EXPECT_EQ (neighbor_ids_handle, std::vector<t8_locidx_t> (neigh_ids, neigh_ids + num_neighbors));
         // Free memory.
         if (num_neighbors > 0) {
@@ -157,7 +158,6 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
           T8_FREE (neigh_ids);
           T8_FREE (neighbors);
           T8_FREE (dual_faces);
-          T8_FREE (dual_faces_handle);
         }
       }
       // Evolve mesh iterator.

From 885b28b12f0a3c314a26c756bb6bc593036c3f03 Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Wed, 5 Nov 2025 11:30:39 +0100
Subject: [PATCH 10/24] implement cache test

---
 api/t8_mesh_handle/abstract_element.hxx    | 29 +++++-----
 api/t8_mesh_handle/competences.hxx         | 31 +++++++----
 api/t8_mesh_handle/mesh.hxx                | 35 +++++++++++-
 api/t8_mesh_handle/mesh_element.hxx        | 31 +++++++++--
 test/api/t8_mesh_handle/t8_gtest_ghost.cxx | 63 +++++++++++++++++++++-
 5 files changed, 158 insertions(+), 31 deletions(-)

diff --git a/api/t8_mesh_handle/abstract_element.hxx b/api/t8_mesh_handle/abstract_element.hxx
index c8c5392309..d022bfee69 100644
--- a/api/t8_mesh_handle/abstract_element.hxx
+++ b/api/t8_mesh_handle/abstract_element.hxx
@@ -142,9 +142,9 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   t8_element_level
   get_level () const
   {
-    const t8_eclass_t tree_class = get_tree_class ();
+    const t8_eclass_t eclass = get_eclass ();
     const t8_element_t* element = get_element ();
-    return t8_forest_get_scheme (m_mesh->m_forest)->element_get_level (tree_class, element);
+    return t8_forest_get_scheme (m_mesh->m_forest)->element_get_level (eclass, element);
   }
 
   /**
@@ -155,7 +155,17 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   int
   get_num_faces () const
   {
-    return t8_forest_get_scheme (m_mesh->m_forest)->element_get_num_faces (get_tree_class (), get_element ());
+    return t8_forest_get_scheme (m_mesh->m_forest)->element_get_num_faces (get_eclass (), get_element ());
+  }
+
+  /**
+   * Getter for the element class of the element.
+   * \return The element class of the element.
+   */
+  t8_eclass_t
+  get_eclass () const
+  {
+    return t8_forest_get_tree_class (m_mesh->m_forest, m_tree_id);
   }
 
   /**
@@ -174,8 +184,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
     }
     // Calculate the vertex coordinates.
     const t8_element_t* element = get_element ();
-    const int num_corners
-      = t8_forest_get_scheme (m_mesh->m_forest)->element_get_num_corners (get_tree_class (), element);
+    const int num_corners = t8_forest_get_scheme (m_mesh->m_forest)->element_get_num_corners (get_eclass (), element);
     std::vector<t8_3D_point> vertex_coordinates;
     vertex_coordinates.reserve (num_corners);
     for (int icorner = 0; icorner < num_corners; ++icorner) {
@@ -264,16 +273,6 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   get_element () const
     = 0;
 
-  /**
-   * Getter for the eclass of the element.
-   * \return The element's eclass.
-   */
-  t8_eclass_t
-  get_tree_class () const
-  {
-    return t8_forest_get_tree_class (m_mesh->m_forest, m_tree_id);
-  }
-
   mesh<TCompetence...>* m_mesh; /**< Pointer to the mesh the element is defined for. */
   t8_locidx_t m_tree_id;        /**< The tree id of the element in the forest defined in the mesh. */
   t8_locidx_t m_element_id;     /**< The element id of the element in the forest defined in the mesh. */
diff --git a/api/t8_mesh_handle/competences.hxx b/api/t8_mesh_handle/competences.hxx
index 69c56f448e..969ca6210a 100644
--- a/api/t8_mesh_handle/competences.hxx
+++ b/api/t8_mesh_handle/competences.hxx
@@ -96,7 +96,7 @@ struct cache_centroid: t8_crtp_operator<TUnderlying, cache_centroid>
 };
 
 /**
- * TODO
+ * Competence to cache the neighbors of an element at a specific face at the first function call.
  * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
  */
 template <typename TUnderlying>
@@ -104,23 +104,36 @@ struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
 {
  public:
   /**
-   * Function that checks if the cache for the centroid has been filled.
-   * \return true if the cache for the centroid has been filled, false otherwise.
+   * Function that checks if the neighbor cache for a face has been filled.
+   * \param [in] face The face for which the cache should be checked.
+   * \return true if the cache has been filled, false otherwise.
    */
   bool
   neighbor_cache_filled (int face) const
   {
-    if (!m_neighbor_indices.empty ())
-      return false;
-    if ((int) m_neighbor_indices.size () <= face)
-      return false;
-    return !m_neighbor_indices[face].empty ();
+    return m_num_neighbors[face].has_value ();
+  }
+
+  /**
+   * Function that checks if the neighbor cache for any face has been filled.
+   * \return true if the cache has been filled, false otherwise.
+   */
+  bool
+  neighbor_cache_filled_any () const
+  {
+    for (int iface = 0; iface < this->underlying ().get_num_faces (); ++iface) {
+      if (neighbor_cache_filled (iface)) {
+        return true;
+      }
+    }
+    return false;
   }
 
  protected:
   mutable std::vector<std::vector<t8_locidx_t>>
     m_neighbor_indices; /**< Element indices of the neighbors at each face. The length of the vectors is stored in \ref m_num_neighbors. */
-  mutable std::vector<int> m_num_neighbors; /**< Vector with the numbers of neighbor elements at each face. */
+  mutable std::vector<std::optional<int>>
+    m_num_neighbors; /**< Vector with the numbers of neighbor elements at each face. */
   mutable std::vector<std::vector<int>>
     m_dual_faces; /**< Face id's of the neighboring elements' faces for each face. */
 };
diff --git a/api/t8_mesh_handle/mesh.hxx b/api/t8_mesh_handle/mesh.hxx
index 1aaf4070aa..308c36532e 100644
--- a/api/t8_mesh_handle/mesh.hxx
+++ b/api/t8_mesh_handle/mesh.hxx
@@ -130,7 +130,8 @@ class mesh {
   }
 
   /**
-   * Getter for an element given its local index. This could be a (local) mesh element or a ghost element. 
+   * Getter for an element given its local index. This could be a (local) mesh element or 
+   *  a ghost element. 
    * The indices 0, 1, ... num_local_el - 1 refer to local mesh elements and 
    *    num_local_el , ... , num_local_el + num_ghosts - 1 refer to ghost elements.
    * \param [in] local_index The local index of the element to access.
@@ -139,6 +140,7 @@ class mesh {
   abstract_element_class&
   operator[] (t8_locidx_t local_index)
   {
+    T8_ASSERT (0 <= local_index && local_index < get_local_num_elements () + get_local_num_ghosts ());
     if (local_index < get_local_num_elements ()) {
       return m_elements[local_index];
     }
@@ -147,6 +149,37 @@ class mesh {
     }
   }
 
+  /**
+   * Getter for a mesh element given its local index. 
+   * This function could be used instead of the operator[] if a mesh element is 
+   * specifically required to access their functionality.
+   * \param [in] local_index The local index of the element to access.
+   * \return Reference to the mesh element.
+   */
+  mesh_element_class&
+  get_mesh_element (t8_locidx_t local_index)
+  {
+    T8_ASSERT (0 <= local_index && local_index < get_local_num_elements ());
+    return m_elements[local_index];
+  }
+
+  /**
+   * Getter for a ghost element given its local flat index. 
+   * This function could be used instead of the operator[] if a ghost element is 
+   * specifically required to access ghost functionality.
+   * \param [in] flat_index The local flat index of the element to access.
+   *             Therefore, flat_index should lie in between num_local_el and
+   *              num_local_el + num_ghosts - 1.
+   * \return Reference to the ghost element.
+   */
+  ghost_element_class&
+  get_ghost_element (t8_locidx_t flat_index)
+  {
+    T8_ASSERT (get_local_num_elements () <= flat_index
+               && flat_index < get_local_num_elements () + get_local_num_ghosts ());
+    return m_ghosts[flat_index - get_local_num_elements ()];
+  }
+
   /**
    * Getter for the forest the mesh is defined for.
    * \return The forest the mesh is defined for.
diff --git a/api/t8_mesh_handle/mesh_element.hxx b/api/t8_mesh_handle/mesh_element.hxx
index 53471bb8f4..dadcd65caf 100644
--- a/api/t8_mesh_handle/mesh_element.hxx
+++ b/api/t8_mesh_handle/mesh_element.hxx
@@ -96,6 +96,16 @@ class mesh_element: public abstract_element<TCompetence...> {
 
  public:
   // --- Functionality special to the mesh element. ---
+  /**
+   * Function that checks if a cache for the face neighbors exists.
+   * \return true if a cache exists, false otherwise.
+   */
+  static constexpr bool
+  has_face_neighbor_cache ()
+  {
+    return neighbor_cache_exists;
+  }
+
   /** Getter for the face neighbors of the mesh element at given face.
    * For ghost elements, the functionality to calculate face neighbors is currently not provided.
    * This function uses the cached version defined in TCompetence if available and calculates if not.
@@ -111,8 +121,8 @@ class mesh_element: public abstract_element<TCompetence...> {
   {
     if constexpr (neighbor_cache_exists) {
       if (this->neighbor_cache_filled (face)) {
-        num_neighbors = &this->m_num_neighbors[face];
-        dual_faces = &(this->m_dual_faces[face]);
+        *num_neighbors = this->m_num_neighbors[face].value ();
+        *dual_faces = this->m_dual_faces[face];
         return this->m_neighbor_indices[face];
       }
     }
@@ -129,8 +139,7 @@ class mesh_element: public abstract_element<TCompetence...> {
     std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
     if (*num_neighbors > 0) {
       /* Free allocated memory. */
-      t8_forest_get_scheme (this->m_mesh->m_forest)
-        ->element_destroy (this->get_tree_class (), *num_neighbors, neighbors);
+      t8_forest_get_scheme (this->m_mesh->m_forest)->element_destroy (this->get_eclass (), *num_neighbors, neighbors);
       T8_FREE (neighbors);
       T8_FREE (dual_faces_internal);
       T8_FREE (neighids);
@@ -144,6 +153,20 @@ class mesh_element: public abstract_element<TCompetence...> {
     return neighbor_ids_vector;
   }
 
+  /**
+   * Function to fill the face neighbor cache for all faces of the mesh element.
+   */
+  void
+  fill_face_neighbor_cache () const
+    requires (neighbor_cache_exists)
+  {
+    for (int iface = 0; iface < this->get_num_faces (); iface++) {
+      int num_neighbors;
+      std::vector<int> dual_faces;
+      get_face_neighbors (iface, &num_neighbors, &dual_faces);
+    }
+  }
+
   /**
    * Implementation of the function to check if the element is a ghost element.
    * \return Always false for the mesh element class.
diff --git a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
index 1a3ecc42e8..d6072c4e29 100644
--- a/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
+++ b/test/api/t8_mesh_handle/t8_gtest_ghost.cxx
@@ -117,8 +117,7 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
 {
   ASSERT_TRUE (t8_forest_is_committed (forest));
 
-  t8_mesh_handle::mesh<t8_mesh_handle::cache_neighbors> mesh
-    = t8_mesh_handle::mesh<t8_mesh_handle::cache_neighbors> (forest);
+  t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
   EXPECT_EQ (mesh.get_local_num_ghosts (), t8_forest_get_num_ghosts (forest));
 
   const t8_scheme* scheme = t8_forest_get_scheme (forest);
@@ -152,6 +151,9 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
         EXPECT_EQ (num_neighbors, num_neighbors_handle);
         EXPECT_EQ (dual_faces_handle, std::vector<int> (dual_faces, dual_faces + num_neighbors));
         EXPECT_EQ (neighbor_ids_handle, std::vector<t8_locidx_t> (neigh_ids, neigh_ids + num_neighbors));
+        for (int ineigh = 0; ineigh < num_neighbors; ineigh++) {
+          EXPECT_EQ (neigh_eclass, mesh[neighbor_ids_handle[ineigh]].get_eclass ());
+        }
         // Free memory.
         if (num_neighbors > 0) {
           scheme->element_destroy (neigh_eclass, num_neighbors, neighbors);
@@ -166,4 +168,61 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
   }
 }
 
+/** Child class of \ref cache_neighbors that allows to modify the cache variables for test purposes. */
+template <typename TUnderlying>
+struct cache_neighbors_overwrite: public t8_mesh_handle::cache_neighbors<TUnderlying>
+{
+ public:
+  /** Overwrites the cache variables for the a \ref face.
+   * \param [in] face              Face for which the cache should be overwritten.
+   * \param [in] neighbor_indices  New cache vector for the neighbor indices.
+   * \param [in] num_neighbors     New cache value for the number of neighbors.
+   * \param [in] dual_faces        New cache vector for the dual faces.
+   */
+  void
+  overwrite_cache (int face, std::vector<t8_locidx_t> neighbor_indices, int num_neighbors, std::vector<int> dual_faces)
+  {
+    this->m_neighbor_indices[face] = neighbor_indices;
+    this->m_num_neighbors[face] = num_neighbors;
+    this->m_dual_faces[face] = dual_faces;
+  }
+};
+
+/** Use child class of \ref cache_neighbors class to check that the cache is actually set 
+ * and accessed correctly. This is done by modifying the cache variables to a unrealistic values and 
+ * checking that the functionality actually outputs this unrealistic value.
+ */
+TEST_P (t8_mesh_ghost_test, cache_neighbors)
+{
+  ASSERT_TRUE (t8_forest_is_committed (forest));
+  using mesh_class = t8_mesh_handle::mesh<cache_neighbors_overwrite>;
+  using element_class = mesh_class::mesh_element_class;
+  mesh_class mesh = mesh_class (forest);
+  EXPECT_TRUE (element_class::has_face_neighbor_cache ());
+
+  const std::vector<t8_locidx_t> unrealistic_neighbor_indices = { 9999, 99989997 };
+  const int unrealistic_num_neighbors = 2;
+  const std::vector<int> unrealistic_dual_faces = { 100, 1012000 };
+  for (auto it = mesh.begin (); it != mesh.end (); ++it) {
+    // Check that cache is empty at the beginning.
+    EXPECT_FALSE (it->neighbor_cache_filled_any ());
+    it->fill_face_neighbor_cache ();
+    for (int iface = 0; iface < it->get_num_faces (); iface++) {
+      EXPECT_TRUE (it->neighbor_cache_filled (iface));
+      int num_neighbors = -1;
+      std::vector<int> dual_faces;
+      auto neighbor_ids = it->get_face_neighbors (iface, &num_neighbors, &dual_faces);
+      EXPECT_EQ ((int) neighbor_ids.size (), num_neighbors);
+      // Overwrite cache with unrealistic values.
+      it->overwrite_cache (iface, unrealistic_neighbor_indices, unrealistic_num_neighbors, unrealistic_dual_faces);
+      EXPECT_TRUE (it->neighbor_cache_filled (iface));
+      neighbor_ids = it->get_face_neighbors (iface, &num_neighbors, &dual_faces);
+      // --- Compare results. ---
+      EXPECT_EQ (neighbor_ids, unrealistic_neighbor_indices);
+      EXPECT_EQ (num_neighbors, unrealistic_num_neighbors);
+      EXPECT_EQ (dual_faces, unrealistic_dual_faces);
+    }
+  }
+}
+
 INSTANTIATE_TEST_SUITE_P (t8_gtest_ghost, t8_mesh_ghost_test, testing::Combine (AllEclasses, testing::Range (1, 2)));

From ed5c9479eda01614a8fd4d969ab3f0817a396c0b Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Wed, 26 Nov 2025 14:06:22 +0100
Subject: [PATCH 11/24] add check for comitted forest to mesh

---
 mesh_handle/mesh.hxx                                   | 2 ++
 test/mesh_handle/t8_gtest_cache_competence.cxx         | 4 ----
 test/mesh_handle/t8_gtest_compare_handle_to_forest.cxx | 1 -
 test/mesh_handle/t8_gtest_custom_competence.cxx        | 1 -
 test/mesh_handle/t8_gtest_ghost.cxx                    | 2 --
 test/mesh_handle/t8_gtest_mesh_handle.cxx              | 6 ------
 6 files changed, 2 insertions(+), 14 deletions(-)

diff --git a/mesh_handle/mesh.hxx b/mesh_handle/mesh.hxx
index ee40d256e1..f535bc7d09 100644
--- a/mesh_handle/mesh.hxx
+++ b/mesh_handle/mesh.hxx
@@ -67,6 +67,7 @@ class mesh {
    */
   mesh (t8_forest_t input_forest): m_forest (input_forest)
   {
+    T8_ASSERT (t8_forest_is_committed (m_forest));
     update_elements ();
   }
 
@@ -179,6 +180,7 @@ class mesh {
   set_forest (t8_forest_t input_forest)
   {
     m_forest = input_forest;
+    T8_ASSERT (t8_forest_is_committed (m_forest));
     update_elements ();
   }
 
diff --git a/test/mesh_handle/t8_gtest_cache_competence.cxx b/test/mesh_handle/t8_gtest_cache_competence.cxx
index b9d9b7f7cf..99dbf630f1 100644
--- a/test/mesh_handle/t8_gtest_cache_competence.cxx
+++ b/test/mesh_handle/t8_gtest_cache_competence.cxx
@@ -96,8 +96,6 @@ class t8_gtest_cache_competence: public testing::Test {
  */
 TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
 {
-  ASSERT_EQ (true, t8_forest_is_committed (forest));
-
   using mesh_class = t8_mesh_handle::mesh<cache_vertex_coordinates_overwrite>;
   using element_class = mesh_class::abstract_element_class;
   mesh_class mesh = mesh_class (forest);
@@ -131,8 +129,6 @@ TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
  */
 TEST_F (t8_gtest_cache_competence, cache_centroid)
 {
-  ASSERT_EQ (true, t8_forest_is_committed (forest));
-
   using mesh_class = t8_mesh_handle::mesh<cache_centroid_overwrite>;
   using element_class = mesh_class::abstract_element_class;
   mesh_class mesh = mesh_class (forest);
diff --git a/test/mesh_handle/t8_gtest_compare_handle_to_forest.cxx b/test/mesh_handle/t8_gtest_compare_handle_to_forest.cxx
index da327eba14..bd0e69f5a8 100644
--- a/test/mesh_handle/t8_gtest_compare_handle_to_forest.cxx
+++ b/test/mesh_handle/t8_gtest_compare_handle_to_forest.cxx
@@ -44,7 +44,6 @@ TEST (t8_gtest_compare_handle_to_forest, compare_handle_to_forest)
   t8_cmesh_t cmesh = t8_cmesh_new_hypercube_hybrid (sc_MPI_COMM_WORLD, 0, 0);
   const t8_scheme *init_scheme = t8_scheme_new_default ();
   t8_forest_t forest = t8_forest_new_uniform (cmesh, init_scheme, level, 0, sc_MPI_COMM_WORLD);
-  ASSERT_EQ (true, t8_forest_is_committed (forest));
 
   t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
 
diff --git a/test/mesh_handle/t8_gtest_custom_competence.cxx b/test/mesh_handle/t8_gtest_custom_competence.cxx
index 1b2c458a65..5500f088c4 100644
--- a/test/mesh_handle/t8_gtest_custom_competence.cxx
+++ b/test/mesh_handle/t8_gtest_custom_competence.cxx
@@ -88,7 +88,6 @@ TEST (t8_gtest_custom_competence, custom_competence)
   t8_cmesh_t cmesh = t8_cmesh_new_hypercube_hybrid (sc_MPI_COMM_WORLD, 0, 0);
   const t8_scheme *scheme = t8_scheme_new_default ();
   t8_forest_t forest = t8_forest_new_uniform (cmesh, scheme, level, 0, sc_MPI_COMM_WORLD);
-  ASSERT_EQ (true, t8_forest_is_committed (forest));
 
   // Check mesh with custom defined competence.
   t8_mesh_handle::mesh<dummy_get_level> mesh = t8_mesh_handle::mesh<dummy_get_level> (forest);
diff --git a/test/mesh_handle/t8_gtest_ghost.cxx b/test/mesh_handle/t8_gtest_ghost.cxx
index 2f57ad2014..42fb5c3e81 100644
--- a/test/mesh_handle/t8_gtest_ghost.cxx
+++ b/test/mesh_handle/t8_gtest_ghost.cxx
@@ -65,7 +65,6 @@ class t8_mesh_ghost_test: public testing::TestWithParam<std::tuple<t8_eclass_t,
 /** Check the implementation of ghosts and all functions accessible by ghosts. */
 TEST_P (t8_mesh_ghost_test, check_ghosts)
 {
-  ASSERT_TRUE (t8_forest_is_committed (forest));
   t8_forest_ghost_print (forest);
 
   t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
@@ -195,7 +194,6 @@ struct cache_neighbors_overwrite: public t8_mesh_handle::cache_neighbors<TUnderl
  */
 TEST_P (t8_mesh_ghost_test, cache_neighbors)
 {
-  ASSERT_TRUE (t8_forest_is_committed (forest));
   using mesh_class = t8_mesh_handle::mesh<cache_neighbors_overwrite>;
   using element_class = mesh_class::mesh_element_class;
   mesh_class mesh = mesh_class (forest);
diff --git a/test/mesh_handle/t8_gtest_mesh_handle.cxx b/test/mesh_handle/t8_gtest_mesh_handle.cxx
index 1df9b7785a..656b5df768 100644
--- a/test/mesh_handle/t8_gtest_mesh_handle.cxx
+++ b/test/mesh_handle/t8_gtest_mesh_handle.cxx
@@ -62,8 +62,6 @@ class t8_mesh_handle_test: public testing::TestWithParam<std::tuple<t8_eclass_t,
 /** Test some default functionality and the iterator of \ref t8_mesh_handle::mesh class. */
 TEST_P (t8_mesh_handle_test, test_iterator)
 {
-  ASSERT_TRUE (t8_forest_is_committed (forest));
-
   // --- Check default functionality. ---
   using mesh_class = t8_mesh_handle::mesh<>;
   using element_class = mesh_class::abstract_element_class;
@@ -99,8 +97,6 @@ TEST_P (t8_mesh_handle_test, test_iterator)
 /** Test competences. */
 TEST_P (t8_mesh_handle_test, test_competences)
 {
-  ASSERT_TRUE (t8_forest_is_committed (forest));
-
   // --- Version with cached vertex coordinates. ---
   using mesh_class_vertex = t8_mesh_handle::mesh<t8_mesh_handle::cache_vertex_coordinates>;
   using element_class_vertex = mesh_class_vertex::abstract_element_class;
@@ -164,8 +160,6 @@ TEST_P (t8_mesh_handle_test, test_competences)
 /** Test mesh (element) class with more than one competence. */
 TEST_P (t8_mesh_handle_test, test_2_competences)
 {
-  ASSERT_TRUE (t8_forest_is_committed (forest));
-
   // --- Use competences to cache level and centroid. ---
   using mesh_class = t8_mesh_handle::mesh<t8_mesh_handle::cache_vertex_coordinates, t8_mesh_handle::cache_centroid>;
   using element_class = mesh_class::abstract_element_class;

From d97a209bf8b081478bb9fb870199cc847b2b0145 Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Wed, 26 Nov 2025 15:17:05 +0100
Subject: [PATCH 12/24] clean up includes

---
 mesh_handle/abstract_element.hxx                | 2 --
 mesh_handle/competences.hxx                     | 2 --
 mesh_handle/ghost_element.hxx                   | 1 -
 mesh_handle/mesh.hxx                            | 2 --
 mesh_handle/mesh_element.hxx                    | 4 ----
 test/mesh_handle/t8_gtest_cache_competence.cxx  | 1 -
 test/mesh_handle/t8_gtest_custom_competence.cxx | 1 -
 test/mesh_handle/t8_gtest_ghost.cxx             | 2 --
 test/mesh_handle/t8_gtest_mesh_handle.cxx       | 1 -
 9 files changed, 16 deletions(-)

diff --git a/mesh_handle/abstract_element.hxx b/mesh_handle/abstract_element.hxx
index 5752899738..951247f575 100644
--- a/mesh_handle/abstract_element.hxx
+++ b/mesh_handle/abstract_element.hxx
@@ -32,10 +32,8 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8_eclass.h>
 #include <t8_forest/t8_forest_general.h>
 #include <t8_forest/t8_forest_geometrical.h>
-#include <t8_forest/t8_forest_balance.h>
 #include <t8_schemes/t8_scheme.hxx>
 #include <t8_types/t8_vec.hxx>
-#include <array>
 #include <vector>
 
 namespace t8_mesh_handle
diff --git a/mesh_handle/competences.hxx b/mesh_handle/competences.hxx
index d93357f7f5..dda7dbd17e 100644
--- a/mesh_handle/competences.hxx
+++ b/mesh_handle/competences.hxx
@@ -41,8 +41,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8.h>
 #include <t8_types/t8_operators.hxx>
 #include <t8_types/t8_vec.hxx>
-#include <t8_eclass.h>
-#include <array>
 #include <vector>
 #include <optional>
 
diff --git a/mesh_handle/ghost_element.hxx b/mesh_handle/ghost_element.hxx
index 0c824abfa7..5af7e32043 100644
--- a/mesh_handle/ghost_element.hxx
+++ b/mesh_handle/ghost_element.hxx
@@ -30,7 +30,6 @@
 #include <t8.h>
 #include "abstract_element.hxx"
 #include <t8_forest/t8_forest_ghost.h>
-#include <vector>
 
 namespace t8_mesh_handle
 {
diff --git a/mesh_handle/mesh.hxx b/mesh_handle/mesh.hxx
index f535bc7d09..683925125d 100644
--- a/mesh_handle/mesh.hxx
+++ b/mesh_handle/mesh.hxx
@@ -33,8 +33,6 @@
 #include "mesh_element.hxx"
 #include "ghost_element.hxx"
 #include <t8_forest/t8_forest_ghost.h>
-#include <iterator>
-#include <memory>
 #include <vector>
 
 namespace t8_mesh_handle
diff --git a/mesh_handle/mesh_element.hxx b/mesh_handle/mesh_element.hxx
index 1afa8ceaa2..74a3988d57 100644
--- a/mesh_handle/mesh_element.hxx
+++ b/mesh_handle/mesh_element.hxx
@@ -32,11 +32,7 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8_element.h>
 #include <t8_eclass.h>
 #include <t8_forest/t8_forest_general.h>
-#include <t8_forest/t8_forest_geometrical.h>
 #include <t8_forest/t8_forest_balance.h>
-#include <t8_schemes/t8_scheme.hxx>
-#include <t8_types/t8_vec.hxx>
-#include <array>
 #include <vector>
 
 namespace t8_mesh_handle
diff --git a/test/mesh_handle/t8_gtest_cache_competence.cxx b/test/mesh_handle/t8_gtest_cache_competence.cxx
index 99dbf630f1..7198fa3b50 100644
--- a/test/mesh_handle/t8_gtest_cache_competence.cxx
+++ b/test/mesh_handle/t8_gtest_cache_competence.cxx
@@ -26,7 +26,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
  */
 
 #include <gtest/gtest.h>
-#include <test/t8_gtest_schemes.hxx>
 #include <t8.h>
 
 #include <mesh_handle/mesh.hxx>
diff --git a/test/mesh_handle/t8_gtest_custom_competence.cxx b/test/mesh_handle/t8_gtest_custom_competence.cxx
index 5500f088c4..491556f2e1 100644
--- a/test/mesh_handle/t8_gtest_custom_competence.cxx
+++ b/test/mesh_handle/t8_gtest_custom_competence.cxx
@@ -26,7 +26,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
  */
 
 #include <gtest/gtest.h>
-#include <test/t8_gtest_schemes.hxx>
 #include <t8.h>
 
 #include <mesh_handle/mesh.hxx>
diff --git a/test/mesh_handle/t8_gtest_ghost.cxx b/test/mesh_handle/t8_gtest_ghost.cxx
index 42fb5c3e81..f63c824b03 100644
--- a/test/mesh_handle/t8_gtest_ghost.cxx
+++ b/test/mesh_handle/t8_gtest_ghost.cxx
@@ -26,7 +26,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
  */
 
 #include <gtest/gtest.h>
-#include <test/t8_gtest_schemes.hxx>
 #include <test/t8_gtest_macros.hxx>
 #include <t8.h>
 
@@ -38,7 +37,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8_forest/t8_forest_balance.h>
 #include <t8_forest/t8_forest_ghost.h>
 #include <t8_schemes/t8_default/t8_default.hxx>
-
 #include <vector>
 
 /** Parametrized test fixture for the ghost tests. */
diff --git a/test/mesh_handle/t8_gtest_mesh_handle.cxx b/test/mesh_handle/t8_gtest_mesh_handle.cxx
index 656b5df768..194aac5d7f 100644
--- a/test/mesh_handle/t8_gtest_mesh_handle.cxx
+++ b/test/mesh_handle/t8_gtest_mesh_handle.cxx
@@ -26,7 +26,6 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
  */
 
 #include <gtest/gtest.h>
-#include <test/t8_gtest_schemes.hxx>
 #include <test/t8_gtest_macros.hxx>
 #include <t8.h>
 

From d789736633e054d6452375e41ef7ce9cc84ec650 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Wed, 17 Dec 2025 16:12:38 +0100
Subject: [PATCH 13/24] fix doxygen

---
 mesh_handle/abstract_element.hxx | 11 ++++++-----
 mesh_handle/competences.hxx      | 11 ++++++-----
 mesh_handle/mesh.hxx             |  6 +++---
 mesh_handle/mesh_element.hxx     |  2 +-
 4 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/mesh_handle/abstract_element.hxx b/mesh_handle/abstract_element.hxx
index 951247f575..9cbd5c7b5b 100644
--- a/mesh_handle/abstract_element.hxx
+++ b/mesh_handle/abstract_element.hxx
@@ -64,9 +64,10 @@ class mesh;
 template <template <typename> class... TCompetence>
 class abstract_element: public TCompetence<abstract_element<TCompetence...>>... {
  protected:
-  using SelfType = abstract_element<TCompetence...>;
-  using mesh_class = mesh<TCompetence...>;
-  friend mesh_class;
+  using SelfType
+    = abstract_element<TCompetence...>;    /**< Type of the current class with all template parameters specified. */
+  using mesh_class = mesh<TCompetence...>; /**< Type of the mesh class the used. */
+  friend mesh_class; /**< Define mesh_class as friend to be able to access e.g. the constructor. */
 
   /**
    * Protected constructor for an element of a mesh. 
@@ -91,7 +92,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   {
     return requires (T<SelfType>& competence) { competence.vertex_cache_filled (); };
   }
-  /* This variable is true if any of the given competences \ref TCompetence implements 
+  /** This variable is true if any of the given competences \a TCompetence implements 
   a function vertex_cache_filled. */
   static constexpr bool vertex_cache_exists = (false || ... || vertex_cache_defined<TCompetence> ());
 
@@ -105,7 +106,7 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   {
     return requires (T<SelfType>& competence) { competence.centroid_cache_filled (); };
   }
-  /* This variable is true if any of the given competences \ref TCompetence implements 
+  /** This variable is true if any of the given competences \a TCompetence implements 
   a function centroid_cache_filled. */
   static constexpr bool centroid_cache_exists = (false || ... || centroid_cache_defined<TCompetence> ());
 
diff --git a/mesh_handle/competences.hxx b/mesh_handle/competences.hxx
index dda7dbd17e..0e65be03bc 100644
--- a/mesh_handle/competences.hxx
+++ b/mesh_handle/competences.hxx
@@ -26,13 +26,14 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
  * is called are provided.
  *
  * All competences have the same inheritance pattern: 
- * We use the CRTP pattern as we may need to access members of the derived class \ref t8_mesh_handle::element. 
+ * We use the CRTP pattern as we may need to access members of the derived classes like 
+ * \ref t8_mesh_handle::abstract_element. 
  * The t8_crtp_operator is used for convenience/clear code (avoid to type a static cast explicitly each time 
  * we need functionality of TUnderlying).
  * Especially for the competences to cache functionality, the access of members is not necessary, 
  * such that it is not obvious why we use the crtp. For competences that extend the functionality of the element, 
  * this is required. 
- * We use it for all competences for consistency and compatibility with the \ref t8_mesh_handle::element class.
+ * We use it for all competences for consistency and compatibility with the \ref t8_mesh_handle::abstract_element class.
  */
 
 #ifndef T8_COMPETENCES_HXX
@@ -49,7 +50,7 @@ namespace t8_mesh_handle
 
 /**
  * Competence to cache the vertex coordinates of an element at the first function call.
- * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
+ * \tparam TUnderlying Use the \ref abstract_element with specified competences as template parameter.
  */
 template <typename TUnderlying>
 struct cache_vertex_coordinates: public t8_crtp_operator<TUnderlying, cache_vertex_coordinates>
@@ -72,7 +73,7 @@ struct cache_vertex_coordinates: public t8_crtp_operator<TUnderlying, cache_vert
 
 /**
  * Competence to cache the centroid of an element at the first function call.
- * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
+ * \tparam TUnderlying Use the \ref abstract_element with specified competences as template parameter.
  */
 template <typename TUnderlying>
 struct cache_centroid: public t8_crtp_operator<TUnderlying, cache_centroid>
@@ -95,7 +96,7 @@ struct cache_centroid: public t8_crtp_operator<TUnderlying, cache_centroid>
 
 /**
  * Competence to cache the neighbors of an element at a specific face at the first function call.
- * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
+ * \tparam TUnderlying Use the \ref abstract_element with specified competences as template parameter.
  */
 template <typename TUnderlying>
 struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
diff --git a/mesh_handle/mesh.hxx b/mesh_handle/mesh.hxx
index 683925125d..88c6371762 100644
--- a/mesh_handle/mesh.hxx
+++ b/mesh_handle/mesh.hxx
@@ -52,9 +52,9 @@ class mesh {
   using mesh_element_class = mesh_element<TCompetence...>;   /**< The mesh element class of the mesh. */
   using ghost_element_class = ghost_element<TCompetence...>; /**< The ghost element class of the mesh. */
   // Declare all element classes as friend such that private members (e.g. the forest) can be accessed.
-  friend abstract_element_class;
-  friend mesh_element_class;
-  friend ghost_element_class;
+  friend abstract_element_class; /**< Abstract element class as friend. */
+  friend mesh_element_class;     /**< Mesh element class as friend. */
+  friend ghost_element_class;    /**< Ghost element class as friend. */
 
   using mesh_const_iterator =
     typename std::vector<mesh_element_class>::const_iterator; /**< Constant iterator type for the mesh elements. */
diff --git a/mesh_handle/mesh_element.hxx b/mesh_handle/mesh_element.hxx
index 74a3988d57..5456e9f067 100644
--- a/mesh_handle/mesh_element.hxx
+++ b/mesh_handle/mesh_element.hxx
@@ -107,7 +107,7 @@ class mesh_element: public abstract_element<TCompetence...> {
    * \param [in]  face          The index of the face across which the face neighbors are searched.
    * \param [out] num_neighbors On output the number of neighbor elements.
    * \param [out] dual_faces    On output the face id's of the neighboring elements' faces.
-   * \return Vector of length \ref num_neighbors with the element indices of the face neighbors.
+   * \return Vector of length \a num_neighbors with the element indices of the face neighbors.
    *         0, 1, ... num_local_el - 1 for local mesh elements and 
    *         num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
    */

From 64c2772276e1caa9e883b5261abd0ef97a8e5e76 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Mon, 5 Jan 2026 14:10:04 +0100
Subject: [PATCH 14/24] reduce to single element class

---
 mesh_handle/README.md                         |   4 +-
 mesh_handle/competences.hxx                   |  10 +-
 .../{abstract_element.hxx => element.hxx}     | 141 +++++++++++--
 mesh_handle/ghost_element.hxx                 |  93 ---------
 mesh_handle/mesh.hxx                          |  63 ++----
 mesh_handle/mesh_element.hxx                  | 190 ------------------
 .../mesh_handle/t8_gtest_cache_competence.cxx |   4 +-
 test/mesh_handle/t8_gtest_ghost.cxx           |   6 +-
 test/mesh_handle/t8_gtest_mesh_handle.cxx     |   8 +-
 9 files changed, 150 insertions(+), 369 deletions(-)
 rename mesh_handle/{abstract_element.hxx => element.hxx} (63%)
 delete mode 100644 mesh_handle/ghost_element.hxx
 delete mode 100644 mesh_handle/mesh_element.hxx

diff --git a/mesh_handle/README.md b/mesh_handle/README.md
index 75dcfeae19..7cb21192ec 100644
--- a/mesh_handle/README.md
+++ b/mesh_handle/README.md
@@ -8,7 +8,5 @@ If you want to use the handle, note that is has its own library. Turn the option
 
 The folder's most important files are: 
 The [mesh.hxx](mesh.hxx) defines the mesh class of the handle. This is the central file of the mesh handle. 
-The [abstract_element.hxx](abstract_element.hxx) defines the common interface of the mesh elements and the ghost elements of the mesh handle.
-The [mesh_element.hxx](mesh_element.hxx) implements a class for the mesh elements of the mesh handle (so non-ghost elements).
-The [ghost_element.hxx](ghost_element.hxx) implements the class for the ghost elements of the mesh handle.
+The [element.hxx](element.hxx) defines the elements (mesh or ghost elements) of the mesh handle.
 The [competences.hxx](competences.hxx) defines additional competences/functionality of an element to access additional data.
diff --git a/mesh_handle/competences.hxx b/mesh_handle/competences.hxx
index 0e65be03bc..dff9dfb07a 100644
--- a/mesh_handle/competences.hxx
+++ b/mesh_handle/competences.hxx
@@ -27,13 +27,13 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
  *
  * All competences have the same inheritance pattern: 
  * We use the CRTP pattern as we may need to access members of the derived classes like 
- * \ref t8_mesh_handle::abstract_element. 
+ * \ref t8_mesh_handle::element. 
  * The t8_crtp_operator is used for convenience/clear code (avoid to type a static cast explicitly each time 
  * we need functionality of TUnderlying).
  * Especially for the competences to cache functionality, the access of members is not necessary, 
  * such that it is not obvious why we use the crtp. For competences that extend the functionality of the element, 
  * this is required. 
- * We use it for all competences for consistency and compatibility with the \ref t8_mesh_handle::abstract_element class.
+ * We use it for all competences for consistency and compatibility with the \ref t8_mesh_handle::element class.
  */
 
 #ifndef T8_COMPETENCES_HXX
@@ -50,7 +50,7 @@ namespace t8_mesh_handle
 
 /**
  * Competence to cache the vertex coordinates of an element at the first function call.
- * \tparam TUnderlying Use the \ref abstract_element with specified competences as template parameter.
+ * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
  */
 template <typename TUnderlying>
 struct cache_vertex_coordinates: public t8_crtp_operator<TUnderlying, cache_vertex_coordinates>
@@ -73,7 +73,7 @@ struct cache_vertex_coordinates: public t8_crtp_operator<TUnderlying, cache_vert
 
 /**
  * Competence to cache the centroid of an element at the first function call.
- * \tparam TUnderlying Use the \ref abstract_element with specified competences as template parameter.
+ * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
  */
 template <typename TUnderlying>
 struct cache_centroid: public t8_crtp_operator<TUnderlying, cache_centroid>
@@ -96,7 +96,7 @@ struct cache_centroid: public t8_crtp_operator<TUnderlying, cache_centroid>
 
 /**
  * Competence to cache the neighbors of an element at a specific face at the first function call.
- * \tparam TUnderlying Use the \ref abstract_element with specified competences as template parameter.
+ * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
  */
 template <typename TUnderlying>
 struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
diff --git a/mesh_handle/abstract_element.hxx b/mesh_handle/element.hxx
similarity index 63%
rename from mesh_handle/abstract_element.hxx
rename to mesh_handle/element.hxx
index 9cbd5c7b5b..4c858acd81 100644
--- a/mesh_handle/abstract_element.hxx
+++ b/mesh_handle/element.hxx
@@ -20,12 +20,12 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** \file abstract_element.hxx
- * Common interface of the mesh elements and the ghost elements of the \ref t8_mesh_handle::mesh handle.
+/** \file element.hxx
+ * Definition of the element class of the \ref t8_mesh_handle::mesh handle (can be ghost or mesh elements).
  */
 
-#ifndef T8_ABSTRACT_ELEMENT_HXX
-#define T8_ABSTRACT_ELEMENT_HXX
+#ifndef T8_ELEMENT_HXX
+#define T8_ELEMENT_HXX
 
 #include <t8.h>
 #include <t8_element.h>
@@ -62,11 +62,10 @@ class mesh;
  * \tparam TCompetence The competences you want to add to the default functionality of the element.
  */
 template <template <typename> class... TCompetence>
-class abstract_element: public TCompetence<abstract_element<TCompetence...>>... {
+class element: public TCompetence<element<TCompetence...>>... {
  protected:
-  using SelfType
-    = abstract_element<TCompetence...>;    /**< Type of the current class with all template parameters specified. */
-  using mesh_class = mesh<TCompetence...>; /**< Type of the mesh class the used. */
+  using SelfType = element<TCompetence...>; /**< Type of the current class with all template parameters specified. */
+  using mesh_class = mesh<TCompetence...>;  /**< Type of the mesh class the used. */
   friend mesh_class; /**< Define mesh_class as friend to be able to access e.g. the constructor. */
 
   /**
@@ -76,9 +75,16 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
    * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
    * \param [in] element_id     The element id of the element in the forest defining the mesh.
    */
-  abstract_element (mesh_class* mesh, t8_locidx_t tree_id, t8_locidx_t element_id)
-    : m_mesh (mesh), m_tree_id (tree_id), m_element_id (element_id)
+  element (mesh_class* mesh, t8_locidx_t tree_id, t8_locidx_t element_id, bool is_ghost_element = false)
+    : m_mesh (mesh), m_tree_id (tree_id), m_element_id (element_id), m_is_ghost_element (is_ghost_element)
   {
+    if constexpr (neighbor_cache_exists) {
+      // Resize neighbor caches for clean access to the caches.
+      const int num_faces = this->get_num_faces ();
+      this->m_num_neighbors.resize (num_faces);
+      this->m_dual_faces.resize (num_faces);
+      this->m_neighbor_indices.resize (num_faces);
+    }
   }
 
   // --- Variables to check which functionality is defined in TCompetence. ---
@@ -106,10 +112,25 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   {
     return requires (T<SelfType>& competence) { competence.centroid_cache_filled (); };
   }
+
   /** This variable is true if any of the given competences \a TCompetence implements 
   a function centroid_cache_filled. */
   static constexpr bool centroid_cache_exists = (false || ... || centroid_cache_defined<TCompetence> ());
 
+  /** Helper function to check if class T implements the function neighbor_cache_filled.
+   * \tparam T The competence to be checked.
+   * \return true if T implements the function, false if not.
+   */
+  template <template <typename> class T>
+  static constexpr bool
+  neighbor_cache_defined ()
+  {
+    return requires (T<SelfType>& competence) { competence.neighbor_cache_filled (0); };
+  }
+  /* This variable is true if any of the given competences \ref TCompetence implements 
+  a function neighbor_cache_filled. */
+  static constexpr bool neighbor_cache_exists = (false || ... || neighbor_cache_defined<TCompetence> ());
+
  public:
   // --- Functions to check if caches exist. ---
   /**
@@ -132,6 +153,16 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
     return centroid_cache_exists;
   }
 
+  /**
+   * Function that checks if a cache for the face neighbors exists.
+   * \return true if a cache exists, false otherwise.
+   */
+  static constexpr bool
+  has_face_neighbor_cache ()
+  {
+    return neighbor_cache_exists;
+  }
+
   // --- Functionality of the element. In each function, it is checked if a cached version exists (and is used then). ---
   /**
    * Getter for the refinement level of the element.
@@ -221,6 +252,67 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
     return coordinates;
   }
 
+  /** Getter for the face neighbors of the mesh element at given face.
+   * For ghost elements, the functionality to calculate face neighbors is currently not provided.
+   * This function uses the cached version defined in TCompetence if available and calculates if not.
+   * \param [in]  face          The index of the face across which the face neighbors are searched.
+   * \param [out] num_neighbors On output the number of neighbor elements.
+   * \param [out] dual_faces    On output the face id's of the neighboring elements' faces.
+   * \return Vector of length \a num_neighbors with the element indices of the face neighbors.
+   *         0, 1, ... num_local_el - 1 for local mesh elements and 
+   *         num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
+   */
+  std::vector<t8_locidx_t>
+  get_face_neighbors (int face, int* num_neighbors, std::vector<int>* dual_faces) const
+  {
+    SC_CHECK_ABORT (!m_is_ghost_element, "get_face_neighbors is not implemented for ghost elements.\n");
+    if constexpr (neighbor_cache_exists) {
+      if (this->neighbor_cache_filled (face)) {
+        *num_neighbors = this->m_num_neighbors[face].value ();
+        *dual_faces = this->m_dual_faces[face];
+        return this->m_neighbor_indices[face];
+      }
+    }
+    std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
+    t8_element_t** neighbors; /*< Neighboring elements. */
+    int* dual_faces_internal; /**< The face indices of the neighbor elements. */
+    t8_locidx_t* neighids;    /*< Neighboring elements ids. */
+    t8_eclass_t neigh_class;  /*< Neighboring elements tree class. */
+
+    t8_forest_leaf_face_neighbors (m_mesh->m_forest, m_tree_id, get_element (), &neighbors, face, &dual_faces_internal,
+                                   num_neighbors, &neighids, &neigh_class, t8_forest_is_balanced (m_mesh->m_forest));
+    dual_faces->assign (dual_faces_internal, dual_faces_internal + *num_neighbors);
+    std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
+    if (*num_neighbors > 0) {
+      /* Free allocated memory. */
+      t8_forest_get_scheme (m_mesh->m_forest)->element_destroy (get_tree_class (), *num_neighbors, neighbors);
+      T8_FREE (neighbors);
+      T8_FREE (dual_faces_internal);
+      T8_FREE (neighids);
+    }
+    if constexpr (neighbor_cache_exists) {
+      this->m_num_neighbors[face] = *num_neighbors;
+      this->m_dual_faces[face] = *dual_faces;
+      this->m_neighbor_indices[face] = std::move (neighbor_ids_vector);
+      return this->m_neighbor_indices[face];
+    }
+    return neighbor_ids_vector;
+  }
+
+  /**
+   * Function to fill the face neighbor cache for all faces of the mesh element.
+   */
+  void
+  fill_face_neighbor_cache () const
+    requires (neighbor_cache_exists)
+  {
+    for (int iface = 0; iface < this->get_num_faces (); iface++) {
+      int num_neighbors;
+      std::vector<int> dual_faces;
+      get_face_neighbors (iface, &num_neighbors, &dual_faces);
+    }
+  }
+
   //--- Getter for the member variables. ---
   /**
    * Getter for the tree id of the element.
@@ -253,12 +345,14 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
   }
 
   /**
-   * Virtual function to check if the element is a ghost element.
+   * Function to check if the element is a ghost element.
    * \return true if the element is a ghost element, false otherwise.
    */
-  virtual constexpr bool
+  bool
   is_ghost_element () const
-    = 0;
+  {
+    return m_is_ghost_element;
+  }
 
  protected:
   //--- Private getter for internal use. ---
@@ -267,9 +361,17 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
    * Has to be implemented differently for mesh elements and ghost elements.
    * \return The leaf element.
    */
-  virtual const t8_element_t*
+  const t8_element_t*
   get_element () const
-    = 0;
+  {
+    if (m_is_ghost_element) {
+      return t8_forest_ghost_get_leaf_element (
+        m_mesh->m_forest, m_tree_id - t8_forest_get_num_local_trees (this->m_mesh->m_forest), m_element_id);
+    }
+    else {
+      return t8_forest_get_leaf_element_in_tree (m_mesh->m_forest, m_tree_id, m_element_id);
+    }
+  }
 
   /**
    * Getter for the eclass of the tree of the element.
@@ -281,10 +383,11 @@ class abstract_element: public TCompetence<abstract_element<TCompetence...>>...
     return t8_forest_get_tree_class (m_mesh->m_forest, m_tree_id);
   }
 
-  mesh_class* m_mesh;       /**< Pointer to the mesh the element is defined for. */
-  t8_locidx_t m_tree_id;    /**< The tree id of the element in the forest defined in the mesh. */
-  t8_locidx_t m_element_id; /**< The element id of the element in the forest defined in the mesh. */
+  mesh_class* m_mesh;            /**< Pointer to the mesh the element is defined for. */
+  t8_locidx_t m_tree_id;         /**< The tree id of the element in the forest defined in the mesh. */
+  t8_locidx_t m_element_id;      /**< The element id of the element in the forest defined in the mesh. */
+  const bool m_is_ghost_element; /**< Flag to indicate if the element is a ghost element. */
 };
 
 }  // namespace t8_mesh_handle
-#endif /* !T8_ABSTRACT_ELEMENT_HXX */
+#endif /* !T8_ELEMENT_HXX */
diff --git a/mesh_handle/ghost_element.hxx b/mesh_handle/ghost_element.hxx
deleted file mode 100644
index 5af7e32043..0000000000
--- a/mesh_handle/ghost_element.hxx
+++ /dev/null
@@ -1,93 +0,0 @@
-/*
-  This file is part of t8code.
-  t8code is a C library to manage a collection (a forest) of multiple
-  connected adaptive space-trees of general element classes in parallel.
-
-  Copyright (C) 2025 the developers
-
-  t8code is free software; you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
-  (at your option) any later version.
-
-  t8code is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with t8code; if not, write to the Free Software Foundation, Inc.,
-  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-*/
-
-/** \file ghost_element.hxx
- * Implementation of the ghost element class of the \ref t8_mesh_handle::mesh handle.
- */
-
-#ifndef T8_GHOST_ELEMENT_HXX
-#define T8_GHOST_ELEMENT_HXX
-
-#include <t8.h>
-#include "abstract_element.hxx"
-#include <t8_forest/t8_forest_ghost.h>
-
-namespace t8_mesh_handle
-{
-/* Forward declaration of the \ref mesh class of the handle.
- */
-template <template <typename> class... TCompetence>
-class mesh;
-
-/** 
- * Class for the ghost elements of the \ref mesh handle. 
- * This class is a child class of the abstract element class and implements the functionality specific to ghost elements.
- * See \ref abstract_element for more information, especially on the template parameter.
- *
- * \tparam TCompetence The competences you want to add to the default functionality of the element.
- */
-template <template <typename> class... TCompetence>
-class ghost_element: public abstract_element<TCompetence...> {
-  using Base = abstract_element<TCompetence...>;
-  using mesh_class = mesh<TCompetence...>;
-  friend mesh_class;
-
-  /**
-   * Constructor for a ghost element. This constructor can only be called by the friend mesh class as
-   * the user should use the mesh class to construct ghost elements.
-   * \param [in] mesh             Pointer to the mesh the ghost element should belong to.
-   * \param [in] tree_id          The tree id of the element (normally the number of local trees + local ghost tree id).
-   * \param [in] lghost_tree_id   The ghost tree id of the element in the forest defining the mesh.
-   * \param [in] element_id       The element id of the element in the forest defining the mesh.
-   */
-  ghost_element (mesh_class* mesh, t8_locidx_t tree_id, t8_locidx_t lghost_tree_id, t8_locidx_t element_id)
-    : Base (mesh, tree_id, element_id), m_lghost_tree_id (lghost_tree_id)
-  {
-  }
-
- public:
-  /**
-   * Implementation of the function to check if the element is a ghost element.
-   * \return Always true for the ghost element class.
-   */
-  constexpr bool
-  is_ghost_element () const override
-  {
-    return true;
-  }
-
- private:
-  /**
-   * Implementation of the getter for the leaf element of the ghost element.
-   * \return The leaf element.
-   */
-  const t8_element_t*
-  get_element () const override
-  {
-    return t8_forest_ghost_get_leaf_element (this->m_mesh->m_forest, m_lghost_tree_id, this->m_element_id);
-  }
-
-  t8_locidx_t m_lghost_tree_id;
-};
-
-}  // namespace t8_mesh_handle
-#endif /* !T8_GHOST_ELEMENT_HXX */
diff --git a/mesh_handle/mesh.hxx b/mesh_handle/mesh.hxx
index 88c6371762..a595e6cfb7 100644
--- a/mesh_handle/mesh.hxx
+++ b/mesh_handle/mesh.hxx
@@ -29,9 +29,7 @@
 
 #include <t8.h>
 #include <t8_forest/t8_forest_general.h>
-#include "abstract_element.hxx"
-#include "mesh_element.hxx"
-#include "ghost_element.hxx"
+#include "element.hxx"
 #include <t8_forest/t8_forest_ghost.h>
 #include <vector>
 
@@ -41,23 +39,19 @@ namespace t8_mesh_handle
 /**
  * Wrapper for a forest that enables it to be handled as a simple mesh object.
  * \tparam TCompetence The competences you want to add to the default functionality of the mesh.
- *         \see abstract_element for more details on the choice of the template parameter.   
+ *         \see element for more details on the choice of the template parameter.   
  */
 template <template <typename> class... TCompetence>
 class mesh {
  public:
   /** Type definitions of the element classes with given competences. */
-  using abstract_element_class = abstract_element<
-    TCompetence...>; /**< The abstract element class of the mesh (could be a mesh element of ghost). */
-  using mesh_element_class = mesh_element<TCompetence...>;   /**< The mesh element class of the mesh. */
-  using ghost_element_class = ghost_element<TCompetence...>; /**< The ghost element class of the mesh. */
-  // Declare all element classes as friend such that private members (e.g. the forest) can be accessed.
-  friend abstract_element_class; /**< Abstract element class as friend. */
-  friend mesh_element_class;     /**< Mesh element class as friend. */
-  friend ghost_element_class;    /**< Ghost element class as friend. */
+  using element_class
+    = element<TCompetence...>; /**< The abstract element class of the mesh (could be a mesh element of ghost). */
+  // Declare element class as friend such that private members (e.g. the forest) can be accessed.
+  friend element_class; /**< Abstract element class as friend. */
 
   using mesh_const_iterator =
-    typename std::vector<mesh_element_class>::const_iterator; /**< Constant iterator type for the mesh elements. */
+    typename std::vector<element_class>::const_iterator; /**< Constant iterator type for the mesh elements. */
 
   /** 
    * Constructor for a mesh of the handle. 
@@ -117,7 +111,7 @@ class mesh {
    * \param [in] local_index The local index of the element to access.
    * \return Reference to the element.
    */
-  const abstract_element_class&
+  const element_class&
   operator[] (t8_locidx_t local_index) const
   {
     T8_ASSERT (0 <= local_index && local_index < get_num_local_elements () + get_num_local_ghosts ());
@@ -129,37 +123,6 @@ class mesh {
     }
   }
 
-  /**
-   * Getter for a mesh element given its local index. 
-   * This function could be used instead of the operator[] if a mesh element is 
-   * specifically required to access their functionality.
-   * \param [in] local_index The local index of the element to access.
-   * \return Reference to the mesh element.
-   */
-  const mesh_element_class&
-  get_mesh_element (t8_locidx_t local_index) const
-  {
-    T8_ASSERT (0 <= local_index && local_index < get_num_local_elements ());
-    return m_elements[local_index];
-  }
-
-  /**
-   * Getter for a ghost element given its local flat index. 
-   * This function could be used instead of the operator[] if a ghost element is 
-   * specifically required to access ghost functionality.
-   * \param [in] flat_index The local flat index of the element to access.
-   *             Therefore, flat_index should lie in between num_local_el and
-   *              num_local_el + num_ghosts - 1.
-   * \return Reference to the ghost element.
-   */
-  const ghost_element_class&
-  get_ghost_element (t8_locidx_t flat_index) const
-  {
-    T8_ASSERT (get_num_local_elements () <= flat_index
-               && flat_index < get_num_local_elements () + get_num_local_ghosts ());
-    return m_ghosts[flat_index - get_num_local_elements ()];
-  }
-
   /**
    * Getter for the forest the mesh is defined for.
    * \return The forest the mesh is defined for.
@@ -196,7 +159,7 @@ class mesh {
     for (t8_locidx_t itree = 0; itree < t8_forest_get_num_local_trees (m_forest); ++itree) {
       const t8_locidx_t num_elems = t8_forest_get_tree_num_leaf_elements (m_forest, itree);
       for (t8_locidx_t ielem = 0; ielem < num_elems; ++ielem) {
-        m_elements.push_back (mesh_element_class (this, itree, ielem));
+        m_elements.push_back (element_class (this, itree, ielem));
       }
     }
     update_ghost_elements ();
@@ -216,14 +179,14 @@ class mesh {
     for (t8_locidx_t itree = 0; itree < t8_forest_get_num_ghost_trees (m_forest); ++itree) {
       const t8_locidx_t num_elems = t8_forest_ghost_tree_num_leaf_elements (m_forest, itree);
       for (t8_locidx_t ielem = 0; ielem < num_elems; ++ielem) {
-        m_ghosts.push_back (ghost_element_class (this, num_loc_trees + itree, itree, ielem));
+        m_ghosts.push_back (element_class (this, num_loc_trees + itree, ielem, true));
       }
     }
   }
 
-  t8_forest_t m_forest;                       /**< The forest the mesh should be defined for. */
-  std::vector<mesh_element_class> m_elements; /**< Vector storing the (local) mesh elements. */
-  std::vector<ghost_element_class> m_ghosts;  /**< Vector storing the (local) ghost elements. */
+  t8_forest_t m_forest;                  /**< The forest the mesh should be defined for. */
+  std::vector<element_class> m_elements; /**< Vector storing the (local) mesh elements. */
+  std::vector<element_class> m_ghosts;   /**< Vector storing the (local) ghost elements. */
 };
 
 }  // namespace t8_mesh_handle
diff --git a/mesh_handle/mesh_element.hxx b/mesh_handle/mesh_element.hxx
deleted file mode 100644
index 5456e9f067..0000000000
--- a/mesh_handle/mesh_element.hxx
+++ /dev/null
@@ -1,190 +0,0 @@
-/*
-This file is part of t8code.
-t8code is a C library to manage a collection (a forest) of multiple
-connected adaptive space-trees of general element classes in parallel.
-
-Copyright (C) 2025 the developers
-
-t8code is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
-
-t8code is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with t8code; if not, write to the Free Software Foundation, Inc.,
-51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-*/
-
-/** \file mesh_element.hxx
- * Implementation of the mesh element class of the \ref t8_mesh_handle::mesh handle.
- */
-
-#ifndef T8_MESH_ELEMENT_HXX
-#define T8_MESH_ELEMENT_HXX
-
-#include <t8.h>
-#include "abstract_element.hxx"
-#include <t8_element.h>
-#include <t8_eclass.h>
-#include <t8_forest/t8_forest_general.h>
-#include <t8_forest/t8_forest_balance.h>
-#include <vector>
-
-namespace t8_mesh_handle
-{
-/* Forward declaration of the \ref mesh class of the handle.
- */
-template <template <typename> class... TCompetence>
-class mesh;
-
-/** 
- * Class for the mesh elements of the mesh handle. 
- * This class is a child class of the abstract element class and implements the functionality specific to mesh elements 
- * (meaning non-ghost elements). See \ref abstract_element for more information, especially on the template parameter.
- *
- * \tparam TCompetence The competences you want to add to the default functionality of the element.
- */
-template <template <typename> class... TCompetence>
-class mesh_element: public abstract_element<TCompetence...> {
-  using Base = abstract_element<TCompetence...>;
-  using SelfType = mesh_element<TCompetence...>;
-  using mesh_class = Base::mesh_class;
-  friend mesh_class;
-
-  // --- Variables to check which functionality is defined in TCompetence. ---
-  /** Helper function to check if class T implements the function neighbor_cache_filled.
-   * \tparam T The competence to be checked.
-   * \return true if T implements the function, false if not.
-   */
-  template <template <typename> class T>
-  static constexpr bool
-  neighbor_cache_defined ()
-  {
-    return requires (T<SelfType>& competence) { competence.neighbor_cache_filled (0); };
-  }
-  /* This variable is true if any of the given competences \ref TCompetence implements 
-  a function neighbor_cache_filled. */
-  static constexpr bool neighbor_cache_exists = (false || ... || neighbor_cache_defined<TCompetence> ());
-
-  /**
-   * Constructor for a mesh element. This constructor can only be called by the friend mesh class as
-   * the user should use the mesh class to construct the elements.
-   * \param [in] mesh           Pointer to the mesh the mesh element should belong to.
-   * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
-   * \param [in] element_id     The element id of the element in the forest defining the mesh.
-   */
-  mesh_element (mesh_class* mesh, t8_locidx_t tree_id, t8_locidx_t element_id): Base (mesh, tree_id, element_id)
-  {
-    if constexpr (neighbor_cache_exists) {
-      // Resize neighbor caches for clean access to the caches.
-      const int num_faces = this->get_num_faces ();
-      this->m_num_neighbors.resize (num_faces);
-      this->m_dual_faces.resize (num_faces);
-      this->m_neighbor_indices.resize (num_faces);
-    }
-  }
-
- public:
-  // --- Functionality special to the mesh element. ---
-  /**
-   * Function that checks if a cache for the face neighbors exists.
-   * \return true if a cache exists, false otherwise.
-   */
-  static constexpr bool
-  has_face_neighbor_cache ()
-  {
-    return neighbor_cache_exists;
-  }
-
-  /** Getter for the face neighbors of the mesh element at given face.
-   * For ghost elements, the functionality to calculate face neighbors is currently not provided.
-   * This function uses the cached version defined in TCompetence if available and calculates if not.
-   * \param [in]  face          The index of the face across which the face neighbors are searched.
-   * \param [out] num_neighbors On output the number of neighbor elements.
-   * \param [out] dual_faces    On output the face id's of the neighboring elements' faces.
-   * \return Vector of length \a num_neighbors with the element indices of the face neighbors.
-   *         0, 1, ... num_local_el - 1 for local mesh elements and 
-   *         num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
-   */
-  std::vector<t8_locidx_t>
-  get_face_neighbors (int face, int* num_neighbors, std::vector<int>* dual_faces) const
-  {
-    if constexpr (neighbor_cache_exists) {
-      if (this->neighbor_cache_filled (face)) {
-        *num_neighbors = this->m_num_neighbors[face].value ();
-        *dual_faces = this->m_dual_faces[face];
-        return this->m_neighbor_indices[face];
-      }
-    }
-    std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
-    t8_element_t** neighbors; /*< Neighboring elements. */
-    int* dual_faces_internal; /**< The face indices of the neighbor elements. */
-    t8_locidx_t* neighids;    /*< Neighboring elements ids. */
-    t8_eclass_t neigh_class;  /*< Neighboring elements tree class. */
-
-    t8_forest_leaf_face_neighbors (this->m_mesh->m_forest, this->m_tree_id, get_element (), &neighbors, face,
-                                   &dual_faces_internal, num_neighbors, &neighids, &neigh_class,
-                                   t8_forest_is_balanced (this->m_mesh->m_forest));
-    dual_faces->assign (dual_faces_internal, dual_faces_internal + *num_neighbors);
-    std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
-    if (*num_neighbors > 0) {
-      /* Free allocated memory. */
-      t8_forest_get_scheme (this->m_mesh->m_forest)
-        ->element_destroy (this->get_tree_class (), *num_neighbors, neighbors);
-      T8_FREE (neighbors);
-      T8_FREE (dual_faces_internal);
-      T8_FREE (neighids);
-    }
-    if constexpr (neighbor_cache_exists) {
-      this->m_num_neighbors[face] = *num_neighbors;
-      this->m_dual_faces[face] = *dual_faces;
-      this->m_neighbor_indices[face] = std::move (neighbor_ids_vector);
-      return this->m_neighbor_indices[face];
-    }
-    return neighbor_ids_vector;
-  }
-
-  /**
-   * Function to fill the face neighbor cache for all faces of the mesh element.
-   */
-  void
-  fill_face_neighbor_cache () const
-    requires (neighbor_cache_exists)
-  {
-    for (int iface = 0; iface < this->get_num_faces (); iface++) {
-      int num_neighbors;
-      std::vector<int> dual_faces;
-      get_face_neighbors (iface, &num_neighbors, &dual_faces);
-    }
-  }
-
-  /**
-   * Implementation of the function to check if the element is a ghost element.
-   * \return Always false for the mesh element class.
-   */
-  constexpr bool
-  is_ghost_element () const override
-  {
-    return false;
-  }
-
- protected:
-  //--- Private getter for internal use. ---
-  /**
-   * Implementation of the getter for the leaf element of the mesh element.
-   * \return The leaf element.
-   */
-  const t8_element_t*
-  get_element () const override
-  {
-    return t8_forest_get_leaf_element_in_tree (this->m_mesh->m_forest, this->m_tree_id, this->m_element_id);
-  }
-};
-
-}  // namespace t8_mesh_handle
-#endif /* !T8_MESH_ELEMENT_HXX */
diff --git a/test/mesh_handle/t8_gtest_cache_competence.cxx b/test/mesh_handle/t8_gtest_cache_competence.cxx
index 7198fa3b50..e5f315b2f3 100644
--- a/test/mesh_handle/t8_gtest_cache_competence.cxx
+++ b/test/mesh_handle/t8_gtest_cache_competence.cxx
@@ -96,7 +96,7 @@ class t8_gtest_cache_competence: public testing::Test {
 TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
 {
   using mesh_class = t8_mesh_handle::mesh<cache_vertex_coordinates_overwrite>;
-  using element_class = mesh_class::abstract_element_class;
+  using element_class = mesh_class::element_class;
   mesh_class mesh = mesh_class (forest);
   EXPECT_TRUE (element_class::has_vertex_cache ());
   EXPECT_FALSE (element_class::has_centroid_cache ());
@@ -129,7 +129,7 @@ TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
 TEST_F (t8_gtest_cache_competence, cache_centroid)
 {
   using mesh_class = t8_mesh_handle::mesh<cache_centroid_overwrite>;
-  using element_class = mesh_class::abstract_element_class;
+  using element_class = mesh_class::element_class;
   mesh_class mesh = mesh_class (forest);
   EXPECT_FALSE (element_class::has_vertex_cache ());
   EXPECT_TRUE (element_class::has_centroid_cache ());
diff --git a/test/mesh_handle/t8_gtest_ghost.cxx b/test/mesh_handle/t8_gtest_ghost.cxx
index f63c824b03..44f1376ef4 100644
--- a/test/mesh_handle/t8_gtest_ghost.cxx
+++ b/test/mesh_handle/t8_gtest_ghost.cxx
@@ -22,7 +22,7 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 
 /**
  * \file t8_gtest_ghost.cxx
- * Tests if the ghost elements and the \ref t8_mesh_handle::mesh_element::get_face_neighbor implementation work as intended.
+ * Tests if the ghost elements and the \ref t8_mesh_handle::element::get_face_neighbor implementation work as intended.
  */
 
 #include <gtest/gtest.h>
@@ -107,7 +107,7 @@ TEST_P (t8_mesh_ghost_test, check_ghosts)
   }
 }
 
-/** Check that the function \ref t8_mesh_handle::mesh_element::get_face_neighbors of the handle works as intended (equal results to forest).*/
+/** Check that the function \ref t8_mesh_handle::element::get_face_neighbors of the handle works as intended (equal results to forest).*/
 TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
 {
   ASSERT_TRUE (t8_forest_is_committed (forest));
@@ -193,7 +193,7 @@ struct cache_neighbors_overwrite: public t8_mesh_handle::cache_neighbors<TUnderl
 TEST_P (t8_mesh_ghost_test, cache_neighbors)
 {
   using mesh_class = t8_mesh_handle::mesh<cache_neighbors_overwrite>;
-  using element_class = mesh_class::mesh_element_class;
+  using element_class = mesh_class::element_class;
   mesh_class mesh = mesh_class (forest);
   EXPECT_TRUE (element_class::has_face_neighbor_cache ());
 
diff --git a/test/mesh_handle/t8_gtest_mesh_handle.cxx b/test/mesh_handle/t8_gtest_mesh_handle.cxx
index 194aac5d7f..ad1ff606fe 100644
--- a/test/mesh_handle/t8_gtest_mesh_handle.cxx
+++ b/test/mesh_handle/t8_gtest_mesh_handle.cxx
@@ -63,7 +63,7 @@ TEST_P (t8_mesh_handle_test, test_iterator)
 {
   // --- Check default functionality. ---
   using mesh_class = t8_mesh_handle::mesh<>;
-  using element_class = mesh_class::abstract_element_class;
+  using element_class = mesh_class::element_class;
   mesh_class mesh = mesh_class (forest);
   EXPECT_FALSE (element_class::has_vertex_cache ());
   EXPECT_FALSE (element_class::has_centroid_cache ());
@@ -98,7 +98,7 @@ TEST_P (t8_mesh_handle_test, test_competences)
 {
   // --- Version with cached vertex coordinates. ---
   using mesh_class_vertex = t8_mesh_handle::mesh<t8_mesh_handle::cache_vertex_coordinates>;
-  using element_class_vertex = mesh_class_vertex::abstract_element_class;
+  using element_class_vertex = mesh_class_vertex::element_class;
   mesh_class_vertex mesh_vertex = mesh_class_vertex (forest);
   EXPECT_TRUE (element_class_vertex::has_vertex_cache ());
   EXPECT_FALSE (element_class_vertex::has_centroid_cache ());
@@ -134,7 +134,7 @@ TEST_P (t8_mesh_handle_test, test_competences)
 
   // --- Version with cached centroid variable. ---
   using mesh_class_centroid = t8_mesh_handle::mesh<t8_mesh_handle::cache_centroid>;
-  using element_class_centroid = mesh_class_centroid::abstract_element_class;
+  using element_class_centroid = mesh_class_centroid::element_class;
   mesh_class_centroid mesh_centroid = mesh_class_centroid (forest);
   EXPECT_FALSE (element_class_centroid::has_vertex_cache ());
   EXPECT_TRUE (element_class_centroid::has_centroid_cache ());
@@ -161,7 +161,7 @@ TEST_P (t8_mesh_handle_test, test_2_competences)
 {
   // --- Use competences to cache level and centroid. ---
   using mesh_class = t8_mesh_handle::mesh<t8_mesh_handle::cache_vertex_coordinates, t8_mesh_handle::cache_centroid>;
-  using element_class = mesh_class::abstract_element_class;
+  using element_class = mesh_class::element_class;
   mesh_class mesh = mesh_class (forest);
   EXPECT_TRUE (element_class::has_vertex_cache ());
   EXPECT_TRUE (element_class::has_centroid_cache ());

From 2d4a1e467e99caf942590c292a3da5a89eab2295 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Mon, 5 Jan 2026 16:25:57 +0100
Subject: [PATCH 15/24] rm num_neighs argument

---
 mesh_handle/competences.hxx         |  2 +-
 mesh_handle/element.hxx             | 33 ++++++++++++++---------------
 test/mesh_handle/t8_gtest_ghost.cxx | 21 ++++++------------
 3 files changed, 23 insertions(+), 33 deletions(-)

diff --git a/mesh_handle/competences.hxx b/mesh_handle/competences.hxx
index dff9dfb07a..0dab83032c 100644
--- a/mesh_handle/competences.hxx
+++ b/mesh_handle/competences.hxx
@@ -132,7 +132,7 @@ struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
   mutable std::vector<std::vector<t8_locidx_t>>
     m_neighbor_indices; /**< Element indices of the neighbors at each face. The length of the vectors is stored in \ref m_num_neighbors. */
   mutable std::vector<std::optional<int>>
-    m_num_neighbors; /**< Vector with the numbers of neighbor elements at each face. */
+    m_num_neighbors; /**< Vector with the numbers of neighbor elements at each face. num_neighbors is stored to indicate that the cache is filled if a face does not have any neighbor. */
   mutable std::vector<std::vector<int>>
     m_dual_faces; /**< Face id's of the neighboring elements' faces for each face. */
 };
diff --git a/mesh_handle/element.hxx b/mesh_handle/element.hxx
index 4c858acd81..b3af03b23b 100644
--- a/mesh_handle/element.hxx
+++ b/mesh_handle/element.hxx
@@ -256,42 +256,42 @@ class element: public TCompetence<element<TCompetence...>>... {
    * For ghost elements, the functionality to calculate face neighbors is currently not provided.
    * This function uses the cached version defined in TCompetence if available and calculates if not.
    * \param [in]  face          The index of the face across which the face neighbors are searched.
-   * \param [out] num_neighbors On output the number of neighbor elements.
    * \param [out] dual_faces    On output the face id's of the neighboring elements' faces.
-   * \return Vector of length \a num_neighbors with the element indices of the face neighbors.
+   * \return Vector of length num_neighbors with the element indices of the face neighbors.
    *         0, 1, ... num_local_el - 1 for local mesh elements and 
    *         num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
    */
   std::vector<t8_locidx_t>
-  get_face_neighbors (int face, int* num_neighbors, std::vector<int>* dual_faces) const
+  get_face_neighbors (int face, std::vector<int>* dual_faces) const
   {
     SC_CHECK_ABORT (!m_is_ghost_element, "get_face_neighbors is not implemented for ghost elements.\n");
     if constexpr (neighbor_cache_exists) {
       if (this->neighbor_cache_filled (face)) {
-        *num_neighbors = this->m_num_neighbors[face].value ();
         *dual_faces = this->m_dual_faces[face];
         return this->m_neighbor_indices[face];
       }
     }
     std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
-    t8_element_t** neighbors; /*< Neighboring elements. */
+    t8_element_t** neighbors; /**< Neighboring elements. */
     int* dual_faces_internal; /**< The face indices of the neighbor elements. */
-    t8_locidx_t* neighids;    /*< Neighboring elements ids. */
-    t8_eclass_t neigh_class;  /*< Neighboring elements tree class. */
+    int num_neighbors;        /**< Number of neighboring elements. */
+    t8_locidx_t* neighids;    /**< Neighboring elements ids. */
+    t8_eclass_t neigh_class;  /**< Neighboring elements tree class. */
 
     t8_forest_leaf_face_neighbors (m_mesh->m_forest, m_tree_id, get_element (), &neighbors, face, &dual_faces_internal,
-                                   num_neighbors, &neighids, &neigh_class, t8_forest_is_balanced (m_mesh->m_forest));
-    dual_faces->assign (dual_faces_internal, dual_faces_internal + *num_neighbors);
-    std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + *num_neighbors);
-    if (*num_neighbors > 0) {
+                                   &num_neighbors, &neighids, &neigh_class, t8_forest_is_balanced (m_mesh->m_forest));
+    dual_faces->assign (dual_faces_internal, dual_faces_internal + num_neighbors);
+    std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + num_neighbors);
+    if (num_neighbors > 0) {
       /* Free allocated memory. */
-      t8_forest_get_scheme (m_mesh->m_forest)->element_destroy (get_tree_class (), *num_neighbors, neighbors);
+      t8_forest_get_scheme (m_mesh->m_forest)->element_destroy (get_tree_class (), num_neighbors, neighbors);
       T8_FREE (neighbors);
       T8_FREE (dual_faces_internal);
       T8_FREE (neighids);
     }
     if constexpr (neighbor_cache_exists) {
-      this->m_num_neighbors[face] = *num_neighbors;
+      // Also store num_neighbors in cache to indicate that the cache is filled if a face does not have any neighbor.
+      this->m_num_neighbors[face] = num_neighbors;
       this->m_dual_faces[face] = *dual_faces;
       this->m_neighbor_indices[face] = std::move (neighbor_ids_vector);
       return this->m_neighbor_indices[face];
@@ -306,10 +306,9 @@ class element: public TCompetence<element<TCompetence...>>... {
   fill_face_neighbor_cache () const
     requires (neighbor_cache_exists)
   {
-    for (int iface = 0; iface < this->get_num_faces (); iface++) {
-      int num_neighbors;
+    for (int iface = 0; iface < get_num_faces (); iface++) {
       std::vector<int> dual_faces;
-      get_face_neighbors (iface, &num_neighbors, &dual_faces);
+      get_face_neighbors (iface, &dual_faces);
     }
   }
 
@@ -366,7 +365,7 @@ class element: public TCompetence<element<TCompetence...>>... {
   {
     if (m_is_ghost_element) {
       return t8_forest_ghost_get_leaf_element (
-        m_mesh->m_forest, m_tree_id - t8_forest_get_num_local_trees (this->m_mesh->m_forest), m_element_id);
+        m_mesh->m_forest, m_tree_id - t8_forest_get_num_local_trees (m_mesh->m_forest), m_element_id);
     }
     else {
       return t8_forest_get_leaf_element_in_tree (m_mesh->m_forest, m_tree_id, m_element_id);
diff --git a/test/mesh_handle/t8_gtest_ghost.cxx b/test/mesh_handle/t8_gtest_ghost.cxx
index 44f1376ef4..bf5e8f4f66 100644
--- a/test/mesh_handle/t8_gtest_ghost.cxx
+++ b/test/mesh_handle/t8_gtest_ghost.cxx
@@ -139,12 +139,10 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
         t8_forest_leaf_face_neighbors (forest, itree, elem, &neighbors, iface, &dual_faces, &num_neighbors, &neigh_ids,
                                        &neigh_eclass, forest_is_balanced);
         // --- Get neighbors from mesh element. ---
-        int num_neighbors_handle;
         std::vector<int> dual_faces_handle;
-        auto neighbor_ids_handle = mesh_iterator->get_face_neighbors (iface, &num_neighbors_handle, &dual_faces_handle);
+        auto neighbor_ids_handle = mesh_iterator->get_face_neighbors (iface, &dual_faces_handle);
         // --- Compare results. ---
-        EXPECT_EQ ((int) neighbor_ids_handle.size (), num_neighbors_handle);
-        EXPECT_EQ (num_neighbors, num_neighbors_handle);
+        EXPECT_EQ (num_neighbors, (int) neighbor_ids_handle.size ());
         EXPECT_EQ (dual_faces_handle, std::vector<int> (dual_faces, dual_faces + num_neighbors));
         EXPECT_EQ (neighbor_ids_handle, std::vector<t8_locidx_t> (neigh_ids, neigh_ids + num_neighbors));
         for (int ineigh = 0; ineigh < num_neighbors; ineigh++) {
@@ -173,15 +171,12 @@ struct cache_neighbors_overwrite: public t8_mesh_handle::cache_neighbors<TUnderl
   /** Overwrites the cache variables for the a \ref face.
    * \param [in] face              Face for which the cache should be overwritten.
    * \param [in] neighbor_indices  New cache vector for the neighbor indices.
-   * \param [in] num_neighbors     New cache value for the number of neighbors.
    * \param [in] dual_faces        New cache vector for the dual faces.
    */
   void
-  overwrite_cache (int face, std::vector<t8_locidx_t> neighbor_indices, int num_neighbors,
-                   std::vector<int> dual_faces) const
+  overwrite_cache (int face, std::vector<t8_locidx_t> neighbor_indices, std::vector<int> dual_faces) const
   {
     this->m_neighbor_indices[face] = neighbor_indices;
-    this->m_num_neighbors[face] = num_neighbors;
     this->m_dual_faces[face] = dual_faces;
   }
 };
@@ -198,7 +193,6 @@ TEST_P (t8_mesh_ghost_test, cache_neighbors)
   EXPECT_TRUE (element_class::has_face_neighbor_cache ());
 
   const std::vector<t8_locidx_t> unrealistic_neighbor_indices = { 9999, 99989997 };
-  const int unrealistic_num_neighbors = 2;
   const std::vector<int> unrealistic_dual_faces = { 100, 1012000 };
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
     // Check that cache is empty at the beginning.
@@ -206,17 +200,14 @@ TEST_P (t8_mesh_ghost_test, cache_neighbors)
     it->fill_face_neighbor_cache ();
     for (int iface = 0; iface < it->get_num_faces (); iface++) {
       EXPECT_TRUE (it->neighbor_cache_filled (iface));
-      int num_neighbors = -1;
       std::vector<int> dual_faces;
-      auto neighbor_ids = it->get_face_neighbors (iface, &num_neighbors, &dual_faces);
-      EXPECT_EQ ((int) neighbor_ids.size (), num_neighbors);
+      auto neighbor_ids = it->get_face_neighbors (iface, &dual_faces);
       // Overwrite cache with unrealistic values.
-      it->overwrite_cache (iface, unrealistic_neighbor_indices, unrealistic_num_neighbors, unrealistic_dual_faces);
+      it->overwrite_cache (iface, unrealistic_neighbor_indices, unrealistic_dual_faces);
       EXPECT_TRUE (it->neighbor_cache_filled (iface));
-      neighbor_ids = it->get_face_neighbors (iface, &num_neighbors, &dual_faces);
+      neighbor_ids = it->get_face_neighbors (iface, &dual_faces);
       // --- Compare results. ---
       EXPECT_EQ (neighbor_ids, unrealistic_neighbor_indices);
-      EXPECT_EQ (num_neighbors, unrealistic_num_neighbors);
       EXPECT_EQ (dual_faces, unrealistic_dual_faces);
     }
   }

From bb8828ead2583775d3c8be6f36d69addfe2c8e6c Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Tue, 6 Jan 2026 09:32:44 +0100
Subject: [PATCH 16/24] cleanup

---
 mesh_handle/competences.hxx |  3 ++-
 mesh_handle/element.hxx     | 37 +++++++++++++++++++------------------
 mesh_handle/mesh.hxx        |  8 ++------
 3 files changed, 23 insertions(+), 25 deletions(-)

diff --git a/mesh_handle/competences.hxx b/mesh_handle/competences.hxx
index 0dab83032c..2647434e1c 100644
--- a/mesh_handle/competences.hxx
+++ b/mesh_handle/competences.hxx
@@ -132,7 +132,8 @@ struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
   mutable std::vector<std::vector<t8_locidx_t>>
     m_neighbor_indices; /**< Element indices of the neighbors at each face. The length of the vectors is stored in \ref m_num_neighbors. */
   mutable std::vector<std::optional<int>>
-    m_num_neighbors; /**< Vector with the numbers of neighbor elements at each face. num_neighbors is stored to indicate that the cache is filled if a face does not have any neighbor. */
+    m_num_neighbors; /**< Vector with the numbers of neighbor elements at each face. 
+                        num_neighbors is stored to indicate that the cache is filled if a face does not have any neighbor. */
   mutable std::vector<std::vector<int>>
     m_dual_faces; /**< Face id's of the neighboring elements' faces for each face. */
 };
diff --git a/mesh_handle/element.hxx b/mesh_handle/element.hxx
index b3af03b23b..a64bb4e58f 100644
--- a/mesh_handle/element.hxx
+++ b/mesh_handle/element.hxx
@@ -38,18 +38,18 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 
 namespace t8_mesh_handle
 {
-/* Forward declaration of the \ref mesh class of the handle.
+/** Forward declaration of the \ref mesh class of the handle.
  */
 template <template <typename> class... TCompetence>
 class mesh;
 
 /** 
- * Common interface of the mesh elements and the ghost elements of the \ref mesh handle.
+ * Definition of the mesh element class of the \ref mesh handle.
  * An element without specified template parameters provides default implementations for basic functionality 
  * as accessing the refinement level or the centroid. With this implementation, the functionality is calculated each time
  * the function is called. 
  * Use the competences defined in \ref competences.hxx as template parameter to cache the functionality instead of 
- * recalculating in every function call.
+ * recalculation in every function call.
  * To add functionality to the element, you can also simply write your own competence class and give it as a template parameter.
  * You can access the functions implemented in your competence via the element. 
  * Please note that the competence should be valid for both, mesh elements and ghost elements.
@@ -65,15 +65,16 @@ template <template <typename> class... TCompetence>
 class element: public TCompetence<element<TCompetence...>>... {
  protected:
   using SelfType = element<TCompetence...>; /**< Type of the current class with all template parameters specified. */
-  using mesh_class = mesh<TCompetence...>;  /**< Type of the mesh class the used. */
+  using mesh_class = mesh<TCompetence...>;  /**< Type of the mesh class used. */
   friend mesh_class; /**< Define mesh_class as friend to be able to access e.g. the constructor. */
 
   /**
-   * Protected constructor for an element of a mesh. 
-   * This constructor of the abstract class should only be called by child classes.
-   * \param [in] mesh           Pointer to the mesh the element should belong to.
-   * \param [in] tree_id        The tree id of the element in the forest defining the mesh.
-   * \param [in] element_id     The element id of the element in the forest defining the mesh.
+   * Protected constructor for an element of a mesh. This could be a simple mesh element or a ghost element.
+   * This constructor should only be called by the mesh_class (and invisible for the user).
+   * \param [in] mesh             Pointer to the mesh the element should belong to.
+   * \param [in] tree_id          The tree id of the element in the forest defining the mesh.
+   * \param [in] element_id       The element id of the element in the forest defining the mesh.
+   * \param [in] is_ghost_element Flag to indicate that this element is a ghost element. Default is false.
    */
   element (mesh_class* mesh, t8_locidx_t tree_id, t8_locidx_t element_id, bool is_ghost_element = false)
     : m_mesh (mesh), m_tree_id (tree_id), m_element_id (element_id), m_is_ghost_element (is_ghost_element)
@@ -112,7 +113,6 @@ class element: public TCompetence<element<TCompetence...>>... {
   {
     return requires (T<SelfType>& competence) { competence.centroid_cache_filled (); };
   }
-
   /** This variable is true if any of the given competences \a TCompetence implements 
   a function centroid_cache_filled. */
   static constexpr bool centroid_cache_exists = (false || ... || centroid_cache_defined<TCompetence> ());
@@ -127,12 +127,12 @@ class element: public TCompetence<element<TCompetence...>>... {
   {
     return requires (T<SelfType>& competence) { competence.neighbor_cache_filled (0); };
   }
-  /* This variable is true if any of the given competences \ref TCompetence implements 
+  /** This variable is true if any of the given competences \ref TCompetence implements 
   a function neighbor_cache_filled. */
   static constexpr bool neighbor_cache_exists = (false || ... || neighbor_cache_defined<TCompetence> ());
 
  public:
-  // --- Functions to check if caches exist. ---
+  // --- Public functions to check if caches exist. ---
   /**
    * Function that checks if a cache for the vertex coordinates exists.
    * \return true if a cache for the vertex coordinates exists, false otherwise.
@@ -273,7 +273,7 @@ class element: public TCompetence<element<TCompetence...>>... {
     }
     std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
     t8_element_t** neighbors; /**< Neighboring elements. */
-    int* dual_faces_internal; /**< The face indices of the neighbor elements. */
+    int* dual_faces_internal; /**< Face indices of the neighbor elements. */
     int num_neighbors;        /**< Number of neighboring elements. */
     t8_locidx_t* neighids;    /**< Neighboring elements ids. */
     t8_eclass_t neigh_class;  /**< Neighboring elements tree class. */
@@ -283,7 +283,7 @@ class element: public TCompetence<element<TCompetence...>>... {
     dual_faces->assign (dual_faces_internal, dual_faces_internal + num_neighbors);
     std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + num_neighbors);
     if (num_neighbors > 0) {
-      /* Free allocated memory. */
+      // Free allocated memory.
       t8_forest_get_scheme (m_mesh->m_forest)->element_destroy (get_tree_class (), num_neighbors, neighbors);
       T8_FREE (neighbors);
       T8_FREE (dual_faces_internal);
@@ -364,6 +364,7 @@ class element: public TCompetence<element<TCompetence...>>... {
   get_element () const
   {
     if (m_is_ghost_element) {
+      // The local ghost tree id is per definition the local tree id - number of local (non-ghost) trees.
       return t8_forest_ghost_get_leaf_element (
         m_mesh->m_forest, m_tree_id - t8_forest_get_num_local_trees (m_mesh->m_forest), m_element_id);
     }
@@ -382,10 +383,10 @@ class element: public TCompetence<element<TCompetence...>>... {
     return t8_forest_get_tree_class (m_mesh->m_forest, m_tree_id);
   }
 
-  mesh_class* m_mesh;            /**< Pointer to the mesh the element is defined for. */
-  t8_locidx_t m_tree_id;         /**< The tree id of the element in the forest defined in the mesh. */
-  t8_locidx_t m_element_id;      /**< The element id of the element in the forest defined in the mesh. */
-  const bool m_is_ghost_element; /**< Flag to indicate if the element is a ghost element. */
+  const mesh_class* m_mesh;       /**< Pointer to the mesh the element is defined for. */
+  const t8_locidx_t m_tree_id;    /**< The tree id of the element in the forest defined in the mesh. */
+  const t8_locidx_t m_element_id; /**< The element id of the element in the forest defined in the mesh. */
+  const bool m_is_ghost_element;  /**< Flag to indicate if the element is a ghost element. */
 };
 
 }  // namespace t8_mesh_handle
diff --git a/mesh_handle/mesh.hxx b/mesh_handle/mesh.hxx
index a595e6cfb7..16a68cf557 100644
--- a/mesh_handle/mesh.hxx
+++ b/mesh_handle/mesh.hxx
@@ -44,12 +44,8 @@ namespace t8_mesh_handle
 template <template <typename> class... TCompetence>
 class mesh {
  public:
-  /** Type definitions of the element classes with given competences. */
-  using element_class
-    = element<TCompetence...>; /**< The abstract element class of the mesh (could be a mesh element of ghost). */
-  // Declare element class as friend such that private members (e.g. the forest) can be accessed.
-  friend element_class; /**< Abstract element class as friend. */
-
+  using element_class = element<TCompetence...>; /**< The element class of the mesh with given competences. */
+  friend element_class; /**< Element class as friend such that private members (e.g. the forest) can be accessed. */
   using mesh_const_iterator =
     typename std::vector<element_class>::const_iterator; /**< Constant iterator type for the mesh elements. */
 

From 9e79d6d3c1337fef18a6d1c87a0d11302b3ad531 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Tue, 6 Jan 2026 09:40:51 +0100
Subject: [PATCH 17/24] Cache element from forest

---
 mesh_handle/element.hxx | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/mesh_handle/element.hxx b/mesh_handle/element.hxx
index a64bb4e58f..73d57ca110 100644
--- a/mesh_handle/element.hxx
+++ b/mesh_handle/element.hxx
@@ -79,6 +79,15 @@ class element: public TCompetence<element<TCompetence...>>... {
   element (mesh_class* mesh, t8_locidx_t tree_id, t8_locidx_t element_id, bool is_ghost_element = false)
     : m_mesh (mesh), m_tree_id (tree_id), m_element_id (element_id), m_is_ghost_element (is_ghost_element)
   {
+    if (m_is_ghost_element) {
+      // The local ghost tree id is per definition the local tree id - number of local (non-ghost) trees.
+      m_element = t8_forest_ghost_get_leaf_element (
+        m_mesh->m_forest, m_tree_id - t8_forest_get_num_local_trees (m_mesh->m_forest), m_element_id);
+    }
+    else {
+      m_element = t8_forest_get_leaf_element_in_tree (m_mesh->m_forest, m_tree_id, m_element_id);
+    }
+    
     if constexpr (neighbor_cache_exists) {
       // Resize neighbor caches for clean access to the caches.
       const int num_faces = this->get_num_faces ();
@@ -357,20 +366,12 @@ class element: public TCompetence<element<TCompetence...>>... {
   //--- Private getter for internal use. ---
   /**
    * Getter for the leaf element of the element.
-   * Has to be implemented differently for mesh elements and ghost elements.
    * \return The leaf element.
    */
   const t8_element_t*
   get_element () const
   {
-    if (m_is_ghost_element) {
-      // The local ghost tree id is per definition the local tree id - number of local (non-ghost) trees.
-      return t8_forest_ghost_get_leaf_element (
-        m_mesh->m_forest, m_tree_id - t8_forest_get_num_local_trees (m_mesh->m_forest), m_element_id);
-    }
-    else {
-      return t8_forest_get_leaf_element_in_tree (m_mesh->m_forest, m_tree_id, m_element_id);
-    }
+    return m_element;
   }
 
   /**
@@ -387,6 +388,7 @@ class element: public TCompetence<element<TCompetence...>>... {
   const t8_locidx_t m_tree_id;    /**< The tree id of the element in the forest defined in the mesh. */
   const t8_locidx_t m_element_id; /**< The element id of the element in the forest defined in the mesh. */
   const bool m_is_ghost_element;  /**< Flag to indicate if the element is a ghost element. */
+  const t8_element_t* m_element;  /**< Cache the pointer to element in the forest as this is often needed. */
 };
 
 }  // namespace t8_mesh_handle

From 659a4ac64f464f1cccc1dd9edb7e134b97941067 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Tue, 6 Jan 2026 10:14:54 +0100
Subject: [PATCH 18/24] make dual_faces parameter optional

---
 mesh_handle/element.hxx | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/mesh_handle/element.hxx b/mesh_handle/element.hxx
index 73d57ca110..9c44439315 100644
--- a/mesh_handle/element.hxx
+++ b/mesh_handle/element.hxx
@@ -87,7 +87,7 @@ class element: public TCompetence<element<TCompetence...>>... {
     else {
       m_element = t8_forest_get_leaf_element_in_tree (m_mesh->m_forest, m_tree_id, m_element_id);
     }
-    
+
     if constexpr (neighbor_cache_exists) {
       // Resize neighbor caches for clean access to the caches.
       const int num_faces = this->get_num_faces ();
@@ -271,12 +271,14 @@ class element: public TCompetence<element<TCompetence...>>... {
    *         num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
    */
   std::vector<t8_locidx_t>
-  get_face_neighbors (int face, std::vector<int>* dual_faces) const
+  get_face_neighbors (int face, std::vector<int>* dual_faces = nullptr) const
   {
     SC_CHECK_ABORT (!m_is_ghost_element, "get_face_neighbors is not implemented for ghost elements.\n");
     if constexpr (neighbor_cache_exists) {
       if (this->neighbor_cache_filled (face)) {
-        *dual_faces = this->m_dual_faces[face];
+        if (dual_faces) {
+          *dual_faces = this->m_dual_faces[face];
+        }
         return this->m_neighbor_indices[face];
       }
     }
@@ -289,8 +291,16 @@ class element: public TCompetence<element<TCompetence...>>... {
 
     t8_forest_leaf_face_neighbors (m_mesh->m_forest, m_tree_id, get_element (), &neighbors, face, &dual_faces_internal,
                                    &num_neighbors, &neighids, &neigh_class, t8_forest_is_balanced (m_mesh->m_forest));
-    dual_faces->assign (dual_faces_internal, dual_faces_internal + num_neighbors);
+    if (dual_faces) {
+      dual_faces->assign (dual_faces_internal, dual_faces_internal + num_neighbors);
+    }
     std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + num_neighbors);
+    if constexpr (neighbor_cache_exists) {
+      // Also store num_neighbors in cache to indicate that the cache is filled if a face does not have any neighbor.
+      this->m_num_neighbors[face] = num_neighbors;
+      this->m_dual_faces[face].assign (dual_faces_internal, dual_faces_internal + num_neighbors);
+      this->m_neighbor_indices[face] = std::move (neighbor_ids_vector);
+    }
     if (num_neighbors > 0) {
       // Free allocated memory.
       t8_forest_get_scheme (m_mesh->m_forest)->element_destroy (get_tree_class (), num_neighbors, neighbors);
@@ -299,10 +309,6 @@ class element: public TCompetence<element<TCompetence...>>... {
       T8_FREE (neighids);
     }
     if constexpr (neighbor_cache_exists) {
-      // Also store num_neighbors in cache to indicate that the cache is filled if a face does not have any neighbor.
-      this->m_num_neighbors[face] = num_neighbors;
-      this->m_dual_faces[face] = *dual_faces;
-      this->m_neighbor_indices[face] = std::move (neighbor_ids_vector);
       return this->m_neighbor_indices[face];
     }
     return neighbor_ids_vector;
@@ -316,8 +322,7 @@ class element: public TCompetence<element<TCompetence...>>... {
     requires (neighbor_cache_exists)
   {
     for (int iface = 0; iface < get_num_faces (); iface++) {
-      std::vector<int> dual_faces;
-      get_face_neighbors (iface, &dual_faces);
+      get_face_neighbors (iface);
     }
   }
 

From 88cfa56e6af1840a0e7190af93308741ef53e0c2 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Tue, 6 Jan 2026 12:29:20 +0100
Subject: [PATCH 19/24] return ptr to elements instead of indices in
 get_face_neigh

---
 mesh_handle/competences.hxx         |  4 +--
 mesh_handle/element.hxx             | 45 ++++++++++++++++++++---------
 test/mesh_handle/t8_gtest_ghost.cxx | 30 +++++++++++--------
 3 files changed, 51 insertions(+), 28 deletions(-)

diff --git a/mesh_handle/competences.hxx b/mesh_handle/competences.hxx
index 2647434e1c..d4bc37a5b0 100644
--- a/mesh_handle/competences.hxx
+++ b/mesh_handle/competences.hxx
@@ -129,8 +129,8 @@ struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
   }
 
  protected:
-  mutable std::vector<std::vector<t8_locidx_t>>
-    m_neighbor_indices; /**< Element indices of the neighbors at each face. The length of the vectors is stored in \ref m_num_neighbors. */
+  mutable std::vector<std::vector<const TUnderlying *>>
+    m_neighbors; /**< Neighboring elements at each face. The length of the vectors is stored in \ref m_num_neighbors. */
   mutable std::vector<std::optional<int>>
     m_num_neighbors; /**< Vector with the numbers of neighbor elements at each face. 
                         num_neighbors is stored to indicate that the cache is filled if a face does not have any neighbor. */
diff --git a/mesh_handle/element.hxx b/mesh_handle/element.hxx
index 9c44439315..4304ddaa73 100644
--- a/mesh_handle/element.hxx
+++ b/mesh_handle/element.hxx
@@ -93,7 +93,7 @@ class element: public TCompetence<element<TCompetence...>>... {
       const int num_faces = this->get_num_faces ();
       this->m_num_neighbors.resize (num_faces);
       this->m_dual_faces.resize (num_faces);
-      this->m_neighbor_indices.resize (num_faces);
+      this->m_neighbors.resize (num_faces);
     }
   }
 
@@ -136,7 +136,7 @@ class element: public TCompetence<element<TCompetence...>>... {
   {
     return requires (T<SelfType>& competence) { competence.neighbor_cache_filled (0); };
   }
-  /** This variable is true if any of the given competences \ref TCompetence implements 
+  /** This variable is true if any of the given competences \a TCompetence implements 
   a function neighbor_cache_filled. */
   static constexpr bool neighbor_cache_exists = (false || ... || neighbor_cache_defined<TCompetence> ());
 
@@ -266,11 +266,9 @@ class element: public TCompetence<element<TCompetence...>>... {
    * This function uses the cached version defined in TCompetence if available and calculates if not.
    * \param [in]  face          The index of the face across which the face neighbors are searched.
    * \param [out] dual_faces    On output the face id's of the neighboring elements' faces.
-   * \return Vector of length num_neighbors with the element indices of the face neighbors.
-   *         0, 1, ... num_local_el - 1 for local mesh elements and 
-   *         num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
+   * \return Vector of length num_neighbors with pointers to the elements neighboring at the given face.
    */
-  std::vector<t8_locidx_t>
+  std::vector<const SelfType*>
   get_face_neighbors (int face, std::vector<int>* dual_faces = nullptr) const
   {
     SC_CHECK_ABORT (!m_is_ghost_element, "get_face_neighbors is not implemented for ghost elements.\n");
@@ -279,7 +277,7 @@ class element: public TCompetence<element<TCompetence...>>... {
         if (dual_faces) {
           *dual_faces = this->m_dual_faces[face];
         }
-        return this->m_neighbor_indices[face];
+        return this->m_neighbors[face];
       }
     }
     std::vector<std::reference_wrapper<SelfType>> neighbor_elements;
@@ -294,12 +292,15 @@ class element: public TCompetence<element<TCompetence...>>... {
     if (dual_faces) {
       dual_faces->assign (dual_faces_internal, dual_faces_internal + num_neighbors);
     }
-    std::vector<t8_locidx_t> neighbor_ids_vector (neighids, neighids + num_neighbors);
+    std::vector<const SelfType*> neighbors_handle;
+    for (int ineighs = 0; ineighs < num_neighbors; ineighs++) {
+      neighbors_handle.push_back (&((*m_mesh)[neighids[ineighs]]));
+    }
     if constexpr (neighbor_cache_exists) {
       // Also store num_neighbors in cache to indicate that the cache is filled if a face does not have any neighbor.
       this->m_num_neighbors[face] = num_neighbors;
       this->m_dual_faces[face].assign (dual_faces_internal, dual_faces_internal + num_neighbors);
-      this->m_neighbor_indices[face] = std::move (neighbor_ids_vector);
+      this->m_neighbors[face] = std::move (neighbors_handle);
     }
     if (num_neighbors > 0) {
       // Free allocated memory.
@@ -309,9 +310,9 @@ class element: public TCompetence<element<TCompetence...>>... {
       T8_FREE (neighids);
     }
     if constexpr (neighbor_cache_exists) {
-      return this->m_neighbor_indices[face];
+      return this->m_neighbors[face];
     }
-    return neighbor_ids_vector;
+    return neighbors_handle;
   }
 
   /**
@@ -338,8 +339,8 @@ class element: public TCompetence<element<TCompetence...>>... {
   }
 
   /**
-   * Getter for the local element id of the element.
-   * \return The local element id of the element.
+   * Getter for the local element id in the tree of the element.
+   * \return The local element id in the tree of the element.
    */
   t8_locidx_t
   get_local_element_id () const
@@ -348,7 +349,23 @@ class element: public TCompetence<element<TCompetence...>>... {
   }
 
   /**
-   * Getter for the mesh to which the element is belonging.
+   * Getter for the flat local element id. This is the index of the element in the mesh to which the element belongs.
+   * \return The flat local element id of the element.
+   */
+  t8_locidx_t
+  get_flat_element_id () const
+  {
+    if (m_is_ghost_element) {
+      return m_mesh->get_num_local_elements ()
+             + t8_forest_ghost_get_tree_element_offset (m_mesh->m_forest,
+                                                        m_tree_id - t8_forest_get_num_local_trees (m_mesh->m_forest))
+             + m_element_id;
+    }
+    return t8_forest_get_tree_element_offset (m_mesh->m_forest, m_tree_id) + m_element_id;
+  }
+
+  /**
+   * Getter for the mesh to which the element belongs.
    * \return Reference to the mesh.
    */
   const mesh_class*
diff --git a/test/mesh_handle/t8_gtest_ghost.cxx b/test/mesh_handle/t8_gtest_ghost.cxx
index bf5e8f4f66..aa18df68c6 100644
--- a/test/mesh_handle/t8_gtest_ghost.cxx
+++ b/test/mesh_handle/t8_gtest_ghost.cxx
@@ -140,14 +140,16 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
                                        &neigh_eclass, forest_is_balanced);
         // --- Get neighbors from mesh element. ---
         std::vector<int> dual_faces_handle;
-        auto neighbor_ids_handle = mesh_iterator->get_face_neighbors (iface, &dual_faces_handle);
+        auto neighbors_handle = mesh_iterator->get_face_neighbors (iface, &dual_faces_handle);
         // --- Compare results. ---
-        EXPECT_EQ (num_neighbors, (int) neighbor_ids_handle.size ());
+        EXPECT_EQ (num_neighbors, (int) neighbors_handle.size ());
         EXPECT_EQ (dual_faces_handle, std::vector<int> (dual_faces, dual_faces + num_neighbors));
-        EXPECT_EQ (neighbor_ids_handle, std::vector<t8_locidx_t> (neigh_ids, neigh_ids + num_neighbors));
+        for (int ineighs = 0; ineighs < num_neighbors; ineighs++) {
+          EXPECT_EQ (neighbors_handle[ineighs]->get_flat_element_id (), neigh_ids[ineighs]);
+        }
         for (int ineigh = 0; ineigh < num_neighbors; ineigh++) {
           EXPECT_EQ (scheme->element_get_shape (neigh_eclass, neighbors[ineigh]),
-                     mesh[neighbor_ids_handle[ineigh]].get_shape ());
+                     neighbors_handle[ineigh]->get_shape ());
         }
         // Free memory.
         if (num_neighbors > 0) {
@@ -170,13 +172,13 @@ struct cache_neighbors_overwrite: public t8_mesh_handle::cache_neighbors<TUnderl
  public:
   /** Overwrites the cache variables for the a \ref face.
    * \param [in] face              Face for which the cache should be overwritten.
-   * \param [in] neighbor_indices  New cache vector for the neighbor indices.
+   * \param [in] neighbors         New cache vector for the neighbors.
    * \param [in] dual_faces        New cache vector for the dual faces.
    */
   void
-  overwrite_cache (int face, std::vector<t8_locidx_t> neighbor_indices, std::vector<int> dual_faces) const
+  overwrite_cache (int face, std::vector<const TUnderlying*> neighbors, std::vector<int> dual_faces) const
   {
-    this->m_neighbor_indices[face] = neighbor_indices;
+    this->m_neighbors[face] = neighbors;
     this->m_dual_faces[face] = dual_faces;
   }
 };
@@ -192,7 +194,11 @@ TEST_P (t8_mesh_ghost_test, cache_neighbors)
   mesh_class mesh = mesh_class (forest);
   EXPECT_TRUE (element_class::has_face_neighbor_cache ());
 
-  const std::vector<t8_locidx_t> unrealistic_neighbor_indices = { 9999, 99989997 };
+  if (mesh.get_num_local_elements () == 0) {
+    GTEST_SKIP () << "No local elements in the mesh to test the cache functionality.";
+  }
+  const std::vector<const element_class*> unrealistic_neighbors
+    = { &mesh[0], &mesh[mesh.get_num_local_elements () - 1] };
   const std::vector<int> unrealistic_dual_faces = { 100, 1012000 };
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {
     // Check that cache is empty at the beginning.
@@ -201,13 +207,13 @@ TEST_P (t8_mesh_ghost_test, cache_neighbors)
     for (int iface = 0; iface < it->get_num_faces (); iface++) {
       EXPECT_TRUE (it->neighbor_cache_filled (iface));
       std::vector<int> dual_faces;
-      auto neighbor_ids = it->get_face_neighbors (iface, &dual_faces);
+      auto neighbors = it->get_face_neighbors (iface, &dual_faces);
       // Overwrite cache with unrealistic values.
-      it->overwrite_cache (iface, unrealistic_neighbor_indices, unrealistic_dual_faces);
+      it->overwrite_cache (iface, unrealistic_neighbors, unrealistic_dual_faces);
       EXPECT_TRUE (it->neighbor_cache_filled (iface));
-      neighbor_ids = it->get_face_neighbors (iface, &dual_faces);
+      neighbors = it->get_face_neighbors (iface, &dual_faces);
       // --- Compare results. ---
-      EXPECT_EQ (neighbor_ids, unrealistic_neighbor_indices);
+      EXPECT_EQ (neighbors, unrealistic_neighbors);
       EXPECT_EQ (dual_faces, unrealistic_dual_faces);
     }
   }

From 65d02033a273f091bb8b215f71163dde4f5f0165 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Tue, 6 Jan 2026 12:38:39 +0100
Subject: [PATCH 20/24] add check that we actually have ghosts and test smth

---
 mesh_handle/mesh.hxx                | 10 ++++++++++
 test/mesh_handle/t8_gtest_ghost.cxx |  7 +++++++
 2 files changed, 17 insertions(+)

diff --git a/mesh_handle/mesh.hxx b/mesh_handle/mesh.hxx
index 16a68cf557..62721b62f4 100644
--- a/mesh_handle/mesh.hxx
+++ b/mesh_handle/mesh.hxx
@@ -79,6 +79,16 @@ class mesh {
     return t8_forest_get_num_ghosts (m_forest);
   }
 
+  /** 
+   * Getter for the dimension the mesh handle lives in.
+   * \return The dimension.
+   */
+  int
+  get_dimension () const
+  {
+    return t8_forest_get_dimension (m_forest);
+  }
+
   /**
    * Returns a constant iterator to the first (local) mesh element.
    * \return Constant iterator to the first (local) mesh element.
diff --git a/test/mesh_handle/t8_gtest_ghost.cxx b/test/mesh_handle/t8_gtest_ghost.cxx
index aa18df68c6..88002857b2 100644
--- a/test/mesh_handle/t8_gtest_ghost.cxx
+++ b/test/mesh_handle/t8_gtest_ghost.cxx
@@ -67,6 +67,13 @@ TEST_P (t8_mesh_ghost_test, check_ghosts)
 
   t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
   EXPECT_EQ (mesh.get_num_local_ghosts (), t8_forest_get_num_ghosts (forest));
+  if ((mesh.get_dimension () > 1) && (mesh.get_num_local_elements () > 1)) {
+    // Ensure that we actually have ghost elements in this test.
+    EXPECT_GT (mesh.get_num_local_ghosts (), 0);
+  }
+  else {
+    GTEST_SKIP () << "Skipping test as no ghost elements are created for 1D or single element meshes.";
+  }
 
   // Check that functionality of mesh elements is still valid.
   for (auto it = mesh.begin (); it != mesh.end (); ++it) {

From a0d7fdc48df6a74e3fcb54ab451f6d8d85e3924f Mon Sep 17 00:00:00 2001
From: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>
Date: Thu, 8 Jan 2026 10:12:18 +0100
Subject: [PATCH 21/24] Apply suggestions from code review

Co-authored-by: Sandro Elsweijer <49643115+sandro-elsweijer@users.noreply.github.com>
---
 mesh_handle/element.hxx | 2 +-
 mesh_handle/mesh.hxx    | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/mesh_handle/element.hxx b/mesh_handle/element.hxx
index 4304ddaa73..76a1c2dac9 100644
--- a/mesh_handle/element.hxx
+++ b/mesh_handle/element.hxx
@@ -261,7 +261,7 @@ class element: public TCompetence<element<TCompetence...>>... {
     return coordinates;
   }
 
-  /** Getter for the face neighbors of the mesh element at given face.
+  /** Getter for the face neighbors of the mesh element at a given face.
    * For ghost elements, the functionality to calculate face neighbors is currently not provided.
    * This function uses the cached version defined in TCompetence if available and calculates if not.
    * \param [in]  face          The index of the face across which the face neighbors are searched.
diff --git a/mesh_handle/mesh.hxx b/mesh_handle/mesh.hxx
index 62721b62f4..b973f3bb03 100644
--- a/mesh_handle/mesh.hxx
+++ b/mesh_handle/mesh.hxx
@@ -80,7 +80,7 @@ class mesh {
   }
 
   /** 
-   * Getter for the dimension the mesh handle lives in.
+   * Getter for the dimension of the mesh.
    * \return The dimension.
    */
   int
@@ -146,8 +146,8 @@ class mesh {
   void
   set_forest (t8_forest_t input_forest)
   {
+    T8_ASSERT (t8_forest_is_committed (input_forest));
     m_forest = input_forest;
-    T8_ASSERT (t8_forest_is_committed (m_forest));
     update_elements ();
   }
 

From 4127dd08b2f2d908f8fc3ef70d1b8adf6b2008b1 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Thu, 8 Jan 2026 11:01:03 +0100
Subject: [PATCH 22/24] review

---
 mesh_handle/element.hxx             | 14 ++++++-------
 mesh_handle/mesh.hxx                | 16 +++++++--------
 test/mesh_handle/t8_gtest_ghost.cxx | 32 +++++++----------------------
 3 files changed, 22 insertions(+), 40 deletions(-)

diff --git a/mesh_handle/element.hxx b/mesh_handle/element.hxx
index 76a1c2dac9..6701418ea9 100644
--- a/mesh_handle/element.hxx
+++ b/mesh_handle/element.hxx
@@ -35,6 +35,7 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 #include <t8_schemes/t8_scheme.hxx>
 #include <t8_types/t8_vec.hxx>
 #include <vector>
+#include <optional>
 
 namespace t8_mesh_handle
 {
@@ -63,13 +64,13 @@ class mesh;
  */
 template <template <typename> class... TCompetence>
 class element: public TCompetence<element<TCompetence...>>... {
- protected:
+ private:
   using SelfType = element<TCompetence...>; /**< Type of the current class with all template parameters specified. */
   using mesh_class = mesh<TCompetence...>;  /**< Type of the mesh class used. */
   friend mesh_class; /**< Define mesh_class as friend to be able to access e.g. the constructor. */
 
   /**
-   * Protected constructor for an element of a mesh. This could be a simple mesh element or a ghost element.
+   * Private constructor for an element of a mesh. This could be a simple mesh element or a ghost element.
    * This constructor should only be called by the mesh_class (and invisible for the user).
    * \param [in] mesh             Pointer to the mesh the element should belong to.
    * \param [in] tree_id          The tree id of the element in the forest defining the mesh.
@@ -262,20 +263,19 @@ class element: public TCompetence<element<TCompetence...>>... {
   }
 
   /** Getter for the face neighbors of the mesh element at a given face.
-   * For ghost elements, the functionality to calculate face neighbors is currently not provided.
    * This function uses the cached version defined in TCompetence if available and calculates if not.
    * \param [in]  face          The index of the face across which the face neighbors are searched.
    * \param [out] dual_faces    On output the face id's of the neighboring elements' faces.
    * \return Vector of length num_neighbors with pointers to the elements neighboring at the given face.
    */
   std::vector<const SelfType*>
-  get_face_neighbors (int face, std::vector<int>* dual_faces = nullptr) const
+  get_face_neighbors (int face, std::optional<std::reference_wrapper<std::vector<int>>> dual_faces = std::nullopt) const
   {
     SC_CHECK_ABORT (!m_is_ghost_element, "get_face_neighbors is not implemented for ghost elements.\n");
     if constexpr (neighbor_cache_exists) {
       if (this->neighbor_cache_filled (face)) {
         if (dual_faces) {
-          *dual_faces = this->m_dual_faces[face];
+          dual_faces->get () = this->m_dual_faces[face];
         }
         return this->m_neighbors[face];
       }
@@ -290,7 +290,7 @@ class element: public TCompetence<element<TCompetence...>>... {
     t8_forest_leaf_face_neighbors (m_mesh->m_forest, m_tree_id, get_element (), &neighbors, face, &dual_faces_internal,
                                    &num_neighbors, &neighids, &neigh_class, t8_forest_is_balanced (m_mesh->m_forest));
     if (dual_faces) {
-      dual_faces->assign (dual_faces_internal, dual_faces_internal + num_neighbors);
+      dual_faces->get ().assign (dual_faces_internal, dual_faces_internal + num_neighbors);
     }
     std::vector<const SelfType*> neighbors_handle;
     for (int ineighs = 0; ineighs < num_neighbors; ineighs++) {
@@ -384,7 +384,7 @@ class element: public TCompetence<element<TCompetence...>>... {
     return m_is_ghost_element;
   }
 
- protected:
+ private:
   //--- Private getter for internal use. ---
   /**
    * Getter for the leaf element of the element.
diff --git a/mesh_handle/mesh.hxx b/mesh_handle/mesh.hxx
index b973f3bb03..152e2e2bd8 100644
--- a/mesh_handle/mesh.hxx
+++ b/mesh_handle/mesh.hxx
@@ -60,9 +60,9 @@ class mesh {
   }
 
   /**
-  * Getter for the number of local elements in the mesh.
-  * \return Number of local elements in the mesh.
-  */
+   * Getter for the number of local elements in the mesh.
+   * \return Number of local elements in the mesh.
+   */
   t8_locidx_t
   get_num_local_elements () const
   {
@@ -70,11 +70,11 @@ class mesh {
   }
 
   /**
-   * Getter for the number of local ghost elements.
-   * \return Number of local ghost elements in the mesh.
+   * Getter for the number of ghost elements.
+   * \return Number of ghost elements in the mesh.
    */
   t8_locidx_t
-  get_num_local_ghosts () const
+  get_num_ghosts () const
   {
     return t8_forest_get_num_ghosts (m_forest);
   }
@@ -120,7 +120,7 @@ class mesh {
   const element_class&
   operator[] (t8_locidx_t local_index) const
   {
-    T8_ASSERT (0 <= local_index && local_index < get_num_local_elements () + get_num_local_ghosts ());
+    T8_ASSERT (0 <= local_index && local_index < get_num_local_elements () + get_num_ghosts ());
     if (local_index < get_num_local_elements ()) {
       return m_elements[local_index];
     }
@@ -179,7 +179,7 @@ class mesh {
   {
     // Clear the ghost vector if already created.
     m_ghosts.clear ();
-    m_ghosts.reserve (get_num_local_ghosts ());
+    m_ghosts.reserve (get_num_ghosts ());
     t8_locidx_t num_loc_trees = t8_forest_get_num_local_trees (m_forest);
 
     for (t8_locidx_t itree = 0; itree < t8_forest_get_num_ghost_trees (m_forest); ++itree) {
diff --git a/test/mesh_handle/t8_gtest_ghost.cxx b/test/mesh_handle/t8_gtest_ghost.cxx
index 88002857b2..011605b021 100644
--- a/test/mesh_handle/t8_gtest_ghost.cxx
+++ b/test/mesh_handle/t8_gtest_ghost.cxx
@@ -66,36 +66,18 @@ TEST_P (t8_mesh_ghost_test, check_ghosts)
   t8_forest_ghost_print (forest);
 
   t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
-  EXPECT_EQ (mesh.get_num_local_ghosts (), t8_forest_get_num_ghosts (forest));
+  EXPECT_EQ (mesh.get_num_ghosts (), t8_forest_get_num_ghosts (forest));
   if ((mesh.get_dimension () > 1) && (mesh.get_num_local_elements () > 1)) {
     // Ensure that we actually have ghost elements in this test.
-    EXPECT_GT (mesh.get_num_local_ghosts (), 0);
+    EXPECT_GT (mesh.get_num_ghosts (), 0);
   }
   else {
     GTEST_SKIP () << "Skipping test as no ghost elements are created for 1D or single element meshes.";
   }
 
-  // Check that functionality of mesh elements is still valid.
-  for (auto it = mesh.begin (); it != mesh.end (); ++it) {
-    EXPECT_FALSE (it->is_ghost_element ());
-    EXPECT_EQ (level, it->get_level ());
-    auto centroid = it->get_centroid ();
-    for (const auto& coordinate : centroid) {
-      EXPECT_GE (1, coordinate);
-      EXPECT_LE (0, coordinate);
-    }
-    auto vertex_coordinates = (*it).get_vertex_coordinates ();
-    for (int ivertex = 0; ivertex < (int) vertex_coordinates.size (); ++ivertex) {
-      for (const auto& coordinate : vertex_coordinates[ivertex]) {
-        EXPECT_GE (1, coordinate);
-        EXPECT_LE (0, coordinate);
-      }
-    }
-  }
-
   // Check functions for ghost elements.
   const t8_locidx_t num_local_elements = mesh.get_num_local_elements ();
-  const t8_locidx_t num_ghost_elements = mesh.get_num_local_ghosts ();
+  const t8_locidx_t num_ghost_elements = mesh.get_num_ghosts ();
   for (t8_locidx_t ighost = num_local_elements; ighost < num_local_elements + num_ghost_elements; ++ighost) {
     EXPECT_TRUE (mesh[ighost].is_ghost_element ());
     EXPECT_EQ (level, mesh[ighost].get_level ());
@@ -120,7 +102,7 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
   ASSERT_TRUE (t8_forest_is_committed (forest));
 
   t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
-  EXPECT_EQ (mesh.get_num_local_ghosts (), t8_forest_get_num_ghosts (forest));
+  EXPECT_EQ (mesh.get_num_ghosts (), t8_forest_get_num_ghosts (forest));
 
   // Iterate over the elements of the forest and of the mesh handle simultaneously and compare results.
   const t8_scheme* scheme = t8_forest_get_scheme (forest);
@@ -147,7 +129,7 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
                                        &neigh_eclass, forest_is_balanced);
         // --- Get neighbors from mesh element. ---
         std::vector<int> dual_faces_handle;
-        auto neighbors_handle = mesh_iterator->get_face_neighbors (iface, &dual_faces_handle);
+        auto neighbors_handle = mesh_iterator->get_face_neighbors (iface, dual_faces_handle);
         // --- Compare results. ---
         EXPECT_EQ (num_neighbors, (int) neighbors_handle.size ());
         EXPECT_EQ (dual_faces_handle, std::vector<int> (dual_faces, dual_faces + num_neighbors));
@@ -214,11 +196,11 @@ TEST_P (t8_mesh_ghost_test, cache_neighbors)
     for (int iface = 0; iface < it->get_num_faces (); iface++) {
       EXPECT_TRUE (it->neighbor_cache_filled (iface));
       std::vector<int> dual_faces;
-      auto neighbors = it->get_face_neighbors (iface, &dual_faces);
+      auto neighbors = it->get_face_neighbors (iface, dual_faces);
       // Overwrite cache with unrealistic values.
       it->overwrite_cache (iface, unrealistic_neighbors, unrealistic_dual_faces);
       EXPECT_TRUE (it->neighbor_cache_filled (iface));
-      neighbors = it->get_face_neighbors (iface, &dual_faces);
+      neighbors = it->get_face_neighbors (iface, dual_faces);
       // --- Compare results. ---
       EXPECT_EQ (neighbors, unrealistic_neighbors);
       EXPECT_EQ (dual_faces, unrealistic_dual_faces);

From 13b23b63f749b2726751a6a48e73e73c8a128c47 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Thu, 8 Jan 2026 15:32:57 +0100
Subject: [PATCH 23/24] better doku and renaming

---
 mesh_handle/element.hxx             | 44 ++++++++++++++++-------------
 test/mesh_handle/t8_gtest_ghost.cxx |  2 +-
 2 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/mesh_handle/element.hxx b/mesh_handle/element.hxx
index 6701418ea9..9c35440d54 100644
--- a/mesh_handle/element.hxx
+++ b/mesh_handle/element.hxx
@@ -327,41 +327,47 @@ class element: public TCompetence<element<TCompetence...>>... {
     }
   }
 
-  //--- Getter for the member variables. ---
+  // --- Function to access mesh specific id. ---
   /**
-   * Getter for the tree id of the element.
-   * \return The element's local tree id.
+   * Getter for the index of the element in the mesh to which the element belongs.
+   * \return The local element id of the element in the mesh.
    */
   t8_locidx_t
-  get_local_tree_id () const
+  get_element_handle_id () const
   {
-    return m_tree_id;
+    if (m_is_ghost_element) {
+      return m_mesh->get_num_local_elements ()
+             + t8_forest_ghost_get_tree_element_offset (m_mesh->m_forest,
+                                                        m_tree_id - t8_forest_get_num_local_trees (m_mesh->m_forest))
+             + m_element_id;
+    }
+    return t8_forest_get_tree_element_offset (m_mesh->m_forest, m_tree_id) + m_element_id;
   }
 
+  //--- Getter for the member variables. ---
   /**
-   * Getter for the local element id in the tree of the element.
-   * \return The local element id in the tree of the element.
+   * Getter for the tree id of the element in the forest related to the mesh.
+   * \warning This is related to t8code's tree structure and should not be confused with \ref mesh specific ids.
+   * This function is mainly relevant for writing custom competences that need to access t8code functionality.
+   * \return The element's local tree id in the forest.
    */
   t8_locidx_t
-  get_local_element_id () const
+  get_local_tree_id () const
   {
-    return m_element_id;
+    return m_tree_id;
   }
 
   /**
-   * Getter for the flat local element id. This is the index of the element in the mesh to which the element belongs.
-   * \return The flat local element id of the element.
+   * Getter for the local element id in the tree of the element in the forest related to the mesh.
+   * \warning This is related to t8code's tree structure and should not be confused with \ref mesh specific ids.
+   * For mesh specific id use \ref get_element_handle_id. 
+   * This function is mainly relevant for writing custom competences that need to access t8code functionality.
+   * \return The local element id in the tree of the element in the forest.
    */
   t8_locidx_t
-  get_flat_element_id () const
+  get_local_element_id () const
   {
-    if (m_is_ghost_element) {
-      return m_mesh->get_num_local_elements ()
-             + t8_forest_ghost_get_tree_element_offset (m_mesh->m_forest,
-                                                        m_tree_id - t8_forest_get_num_local_trees (m_mesh->m_forest))
-             + m_element_id;
-    }
-    return t8_forest_get_tree_element_offset (m_mesh->m_forest, m_tree_id) + m_element_id;
+    return m_element_id;
   }
 
   /**
diff --git a/test/mesh_handle/t8_gtest_ghost.cxx b/test/mesh_handle/t8_gtest_ghost.cxx
index 011605b021..8176e842cc 100644
--- a/test/mesh_handle/t8_gtest_ghost.cxx
+++ b/test/mesh_handle/t8_gtest_ghost.cxx
@@ -134,7 +134,7 @@ TEST_P (t8_mesh_ghost_test, compare_neighbors_to_forest)
         EXPECT_EQ (num_neighbors, (int) neighbors_handle.size ());
         EXPECT_EQ (dual_faces_handle, std::vector<int> (dual_faces, dual_faces + num_neighbors));
         for (int ineighs = 0; ineighs < num_neighbors; ineighs++) {
-          EXPECT_EQ (neighbors_handle[ineighs]->get_flat_element_id (), neigh_ids[ineighs]);
+          EXPECT_EQ (neighbors_handle[ineighs]->get_element_handle_id (), neigh_ids[ineighs]);
         }
         for (int ineigh = 0; ineigh < num_neighbors; ineigh++) {
           EXPECT_EQ (scheme->element_get_shape (neigh_eclass, neighbors[ineigh]),

From 6aedab7b39b6ae8a93074f85ff26ecef6e94ff30 Mon Sep 17 00:00:00 2001
From: Lena Ploetzke <lena.ploetzke@dlr.de>
Date: Fri, 9 Jan 2026 12:09:29 +0100
Subject: [PATCH 24/24] small copy paste error

---
 mesh_handle/competences.hxx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mesh_handle/competences.hxx b/mesh_handle/competences.hxx
index d4bc37a5b0..69a2880868 100644
--- a/mesh_handle/competences.hxx
+++ b/mesh_handle/competences.hxx
@@ -99,7 +99,7 @@ struct cache_centroid: public t8_crtp_operator<TUnderlying, cache_centroid>
  * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
  */
 template <typename TUnderlying>
-struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
+struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_neighbors>
 {
  public:
   /**