Feature: Add a constructor wrapper for the mesh handle

mesh_handle/README.md

@@ -7,6 +7,7 @@ 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` in addition to the usual t8code target please.
 
 The folder's most important files are: 
-The [mesh.hxx](mesh.hxx) defines the mesh of the handle. This is the central file 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.
+- The [mesh.hxx](mesh.hxx) defines the mesh of the handle. This is the central file 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.
+- The [constructor_wrappers.hxx](constructor_wrappers.hxx) allows to define a mesh handle using a cmesh instead of a forest and provides a very small number of examples where the user needs no cmesh.

mesh_handle/constructor_wrappers.hxx

@@ -0,0 +1,117 @@
+/*
+  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) 2026 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 constructor_wrappers.hxx
+ * Wrapper to construct a mesh handle instance from a cmesh. 
+ * Additionally, a very small fraction of example coarse meshes is wrapped directly for easy access and 
+ * for the use in tests.
+ * See \ref t8_cmesh_examples.h for more exemplary cmeshes to be put into the wrapper constructors.
+ */
+
+#pragma once
+
+#include <t8.h>
+#include <t8_forest/t8_forest_general.h>
+#include <t8_cmesh/t8_cmesh.h>
+#include <t8_schemes/t8_default/t8_default.hxx>
+#include <t8_cmesh/t8_cmesh_examples.h>
+#include <memory>
+
+namespace t8_mesh_handle
+{
+
+/** Build a uniformly refined mesh handle on a coarse mesh using a scheme.
+ * \param [in] cmesh         A coarse mesh.
+ * \param [in] scheme        Refinement scheme to use.
+ * \param [in] level         An initial uniform refinement level.
+ * \param [in] comm          MPI communicator to use.
+ * \param [in] do_face_ghost If true, a layer of ghost elements is created.
+ * \tparam TMesh             The mesh handle class.
+ * \return Unique pointer to a uniformly refined mesh handle with coarse mesh \a cmesh and refinement level \a level.
+ */
+template <typename TMesh>
+std::unique_ptr<TMesh>
+handle_new_uniform (const t8_cmesh_t cmesh, const t8_scheme *scheme, const int level, const sc_MPI_Comm comm,
+                    const bool do_face_ghost = false)
+{
+  t8_forest_t forest = t8_forest_new_uniform (cmesh, scheme, level, do_face_ghost, sc_MPI_COMM_WORLD);
+  return std::make_unique<TMesh> (forest);
+}
+
+/** Build a uniformly refined mesh handle on a coarse mesh using a default scheme.
+ * \param [in] cmesh         A coarse mesh.
+ * \param [in] level         An initial uniform refinement level.
+ * \param [in] comm          MPI communicator to use.
+ * \param [in] do_face_ghost If true, a layer of ghost elements is created.
+ * \tparam TMesh             The mesh handle class.
+ * \return Unique pointer to a uniformly refined mesh handle with coarse mesh \a cmesh and refinement level \a level.
+ */
+template <typename TMesh>
+std::unique_ptr<TMesh>
+handle_new_uniform_default (const t8_cmesh_t cmesh, const int level, const sc_MPI_Comm comm,
+                            const bool do_face_ghost = false)
+{
+  return handle_new_uniform<TMesh> (cmesh, t8_scheme_new_default (), level, comm, do_face_ghost);
+}
+
+// --- A very small fraction of example coarse meshes is wrapped here for easy access and for the use in tests. ---
+/** Hybercube with 6 Tets, 6 Prism, 4 Hex. Refined uniformly to given level using the default scheme.
+ * \param [in] level         An initial uniform refinement level.
+ * \param [in] comm          MPI communicator to use.
+ * \param [in] do_partition  If non-zero create a partitioned cmesh.
+ * \param [in] do_face_ghost If true, a layer of ghost elements is created.
+ * \param [in] periodic      If non-zero create a periodic cmesh in each direction.
+ * \tparam TMesh             The mesh handle class.
+ * \return Unique pointer to a uniformly refined mesh handle initially consisting of 6 Tets, 6 prism and 4 hex.
+ *         Together, they form a cube.
+*/
+template <typename TMesh>
+std::unique_ptr<TMesh>
+handle_hypercube_hybrid_uniform_default (const int level, const sc_MPI_Comm comm, const bool do_partition = false,
+                                         const bool do_face_ghost = false, const bool periodic = false)
+{
+  t8_cmesh_t cmesh = t8_cmesh_new_hypercube_hybrid (comm, do_partition, periodic);
+  return handle_new_uniform_default<TMesh> (cmesh, level, comm, do_face_ghost);
+}
+
+/** Construct hybercube from one primitive tree class. Refined uniformly to given level using the default scheme.
+ * \param [in] eclass        This element class determines the dimension and the number of trees needed to construct a cube.
+ * \param [in] level         An initial uniform refinement level.
+ * \param [in] comm          MPI communicator to use.
+ * \param [in] do_partition  If non-zero create a partitioned cmesh.
+ * \param [in] do_face_ghost If true, a layer of ghost elements is created.
+ * \param [in] periodic      If non-zero create a periodic cmesh in each direction. Not possible with \a eclass pyramid.
+ * \tparam TMesh             The mesh handle class.
+ * \return Unique pointer to a uniformly refined mesh handle hypercube.
+*/
+template <typename TMesh>
+std::unique_ptr<TMesh>
+handle_hypercube_uniform_default (t8_eclass_t eclass, const int level, const sc_MPI_Comm comm,
+                                  const bool do_partition = false, const bool do_face_ghost = false,
+                                  const bool periodic = false)
+{
+  // Broadcast option is hidden from the user.
+  t8_cmesh_t cmesh = t8_cmesh_new_hypercube (eclass, comm, 0, do_partition, periodic);
+  return handle_new_uniform_default<TMesh> (cmesh, level, comm, do_face_ghost);
+}
+
+}  // namespace t8_mesh_handle

test/mesh_handle/t8_gtest_cache_competence.cxx

@@ -30,10 +30,7 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 
 #include <mesh_handle/mesh.hxx>
 #include <mesh_handle/competences.hxx>
-#include <t8_cmesh/t8_cmesh.h>
-#include <t8_cmesh/t8_cmesh_examples.h>
-#include <t8_forest/t8_forest_general.h>
-#include <t8_schemes/t8_default/t8_default.hxx>
+#include <mesh_handle/constructor_wrappers.hxx>
 #include <t8_types/t8_vec.hxx>
 #include <vector>
 
@@ -67,37 +64,20 @@ struct cache_centroid_overwrite: public t8_mesh_handle::cache_centroid<TUnderlyi
   }
 };
 
-/** Test fixture for cache competence tests. */
-struct t8_gtest_cache_competence: public testing::Test
-{
- protected:
-  void
-  SetUp () override
-  {
-    level = 1;
-    t8_cmesh_t cmesh = t8_cmesh_new_hypercube_hybrid (sc_MPI_COMM_WORLD, 0, 0);
-    const t8_scheme *scheme = t8_scheme_new_default ();
-    forest = t8_forest_new_uniform (cmesh, scheme, level, 0, sc_MPI_COMM_WORLD);
-  }
-
-  t8_forest_t forest;
-  int level;
-};
-
 /** Use child of \ref t8_mesh_handle::cache_vertex_coordinates to check that the cache is actually set 
  * and accessed correctly. This is done by modifying the cache to an unrealistic value and 
  * checking that the functionality actually outputs this unrealistic value.
  */
-TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
+TEST (t8_gtest_cache_competence, cache_vertex_coordinates)
 {
+  const int level = 1;
   using mesh_class = t8_mesh_handle::mesh<cache_vertex_coordinates_overwrite>;
-  using element_class = mesh_class::element_class;
-  mesh_class mesh = mesh_class (forest);
+  using element_class = typename mesh_class::element_class;
+  const auto mesh = t8_mesh_handle::handle_hypercube_hybrid_uniform_default<mesh_class> (level, sc_MPI_COMM_WORLD);
   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) {
+  for (auto it = mesh->begin (); it != mesh->end (); ++it) {
     // Check that cache is empty at the beginning.
     EXPECT_FALSE (it->vertex_cache_filled ());
     // Check that values are valid.
@@ -121,16 +101,16 @@ TEST_F (t8_gtest_cache_competence, cache_vertex_coordinates)
  * and accessed correctly. This is done by modifying the cache to an unrealistic value and 
  * checking that the functionality actually outputs this unrealistic value.
  */
-TEST_F (t8_gtest_cache_competence, cache_centroid)
+TEST (t8_gtest_cache_competence, cache_centroid)
 {
+  const int level = 1;
   using mesh_class = t8_mesh_handle::mesh<cache_centroid_overwrite>;
   using element_class = mesh_class::element_class;
-  mesh_class mesh = mesh_class (forest);
-  EXPECT_FALSE (element_class::has_vertex_cache ());
+  const auto mesh = t8_mesh_handle::handle_hypercube_hybrid_uniform_default<mesh_class> (level, sc_MPI_COMM_WORLD);
   EXPECT_TRUE (element_class::has_centroid_cache ());
 
   t8_3D_point unrealistic_centroid ({ 999, 1000, 998 });
-  for (auto it = mesh.begin (); it != mesh.end (); ++it) {
+  for (auto it = mesh->begin (); it != mesh->end (); ++it) {
     // Check that cache is empty at the beginning.
     EXPECT_FALSE (it->centroid_cache_filled ());
     // Check that values are valid.

test/mesh_handle/t8_gtest_custom_competence.cxx

@@ -30,10 +30,8 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 
 #include <mesh_handle/mesh.hxx>
 #include <mesh_handle/competences.hxx>
-#include <t8_cmesh/t8_cmesh.h>
-#include <t8_cmesh/t8_cmesh_examples.h>
+#include <mesh_handle/constructor_wrappers.hxx>
 #include <t8_forest/t8_forest_general.h>
-#include <t8_schemes/t8_default/t8_default.hxx>
 #include <t8_types/t8_operators.hxx>
 
 /**
@@ -45,9 +43,9 @@ struct dummy_get_level: public t8_crtp_operator<TUnderlying, dummy_get_level>
 {
  public:
   /** Getter for the level of the element. This function needs to access several members 
-  *     of the element such that we need the crtp structure here. 
-  * \return Level of the element.
-  */
+   *     of the element such that we need the crtp structure here. 
+   * \return Level of the element.
+   */
   t8_element_level
   get_level_dummy () const
   {
@@ -82,26 +80,23 @@ struct dummy_trivial: public t8_crtp_operator<TUnderlying, dummy_trivial>
  */
 TEST (t8_gtest_custom_competence, custom_competence)
 {
-  // Define forest to construct mesh.
-  const int level = 1;
-  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);
-
   // Check mesh with custom defined competence.
-  t8_mesh_handle::mesh<dummy_get_level> mesh = t8_mesh_handle::mesh<dummy_get_level> (forest);
+  using mesh_class = t8_mesh_handle::mesh<dummy_get_level>;
+  const int level = 1;
+  const auto mesh = t8_mesh_handle::handle_hypercube_hybrid_uniform_default<mesh_class> (level, sc_MPI_COMM_WORLD);
 
-  for (auto it = mesh.begin (); it != mesh.end (); ++it) {
+  for (auto it = mesh->begin (); it != mesh->end (); ++it) {
     EXPECT_EQ (it->get_level (), it->get_level_dummy ());
     EXPECT_EQ (level, it->get_level_dummy ());
   }
 
-  t8_forest_ref (forest);
   // Test with two custom competences and a predefined competence.
-  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);
+  using mesh_class_more_competences
+    = t8_mesh_handle::mesh<dummy_get_level, dummy_trivial, t8_mesh_handle::cache_centroid>;
+  auto mesh_more_competences
+    = t8_mesh_handle::handle_hypercube_hybrid_uniform_default<mesh_class_more_competences> (level, sc_MPI_COMM_WORLD);
 
-  for (auto it = mesh_more_competences.begin (); it != mesh_more_competences.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 ());

test/mesh_handle/t8_gtest_ghost.cxx

@@ -31,6 +31,7 @@ along with t8code; if not, write to the Free Software Foundation, Inc.,
 
 #include <mesh_handle/mesh.hxx>
 #include <mesh_handle/competences.hxx>
+#include <mesh_handle/constructor_wrappers.hxx>
 #include <t8_cmesh/t8_cmesh.h>
 #include <t8_cmesh/t8_cmesh_examples.h>
 #include <t8_forest/t8_forest_general.h>
@@ -46,44 +47,42 @@ struct t8_mesh_ghost_test: public testing::TestWithParam<std::tuple<t8_eclass_t,
   void
   SetUp () override
   {
-    const t8_scheme* scheme = t8_scheme_new_default ();
-    t8_eclass_t eclass = std::get<0> (GetParam ());
+    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);
   }
 
-  t8_forest_t forest;
+  t8_eclass_t eclass;
   int level;
 };
 
 /** Check the implementation of ghosts and all functions accessible by ghosts. */
 TEST_P (t8_mesh_ghost_test, check_ghosts)
 {
-  t8_forest_ghost_print (forest);
+  using mesh_class = t8_mesh_handle::mesh<>;
+  auto mesh = t8_mesh_handle::handle_hypercube_uniform_default<mesh_class> (eclass, level, sc_MPI_COMM_WORLD, true,
+                                                                            true, false);
 
-  t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (forest);
-  EXPECT_EQ (mesh.get_num_ghosts (), t8_forest_get_num_ghosts (forest));
-  if ((mesh.get_dimension () > 1) && (mesh.get_num_local_elements () > 1)) {
+  EXPECT_EQ (mesh->get_num_ghosts (), t8_forest_get_num_ghosts (mesh->get_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_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 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_ghosts ();
+  const t8_locidx_t num_local_elements = mesh->get_num_local_elements ();
+  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 ());
-    auto centroid = mesh[ighost].get_centroid ();
+    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 ();
+    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);
@@ -96,23 +95,23 @@ TEST_P (t8_mesh_ghost_test, check_ghosts)
 /** 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));
+  const t8_scheme* scheme = t8_scheme_new_default ();
+  t8_forest_t forest = t8_forest_new_uniform (t8_cmesh_new_hypercube (eclass, sc_MPI_COMM_WORLD, 0, 1, 0), scheme,
+                                              level, 1, sc_MPI_COMM_WORLD);
 
   t8_mesh_handle::mesh<> mesh = t8_mesh_handle::mesh<> (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);
   auto mesh_iterator = mesh.begin ();
   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_local_tree_id (), itree);
       EXPECT_EQ (mesh_iterator->get_local_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);
+      const int num_faces = scheme->element_get_num_faces (t8_forest_get_tree_class (forest, itree), elem);
       EXPECT_EQ (mesh_iterator->get_num_faces (), num_faces);
       for (int iface = 0; iface < num_faces; iface++) {
         // --- Get neighbors from forest. ---
@@ -177,16 +176,17 @@ TEST_P (t8_mesh_ghost_test, cache_neighbors)
 {
   using mesh_class = t8_mesh_handle::mesh<cache_neighbors_overwrite>;
   using element_class = mesh_class::element_class;
-  mesh_class mesh = mesh_class (forest);
+  auto mesh = t8_mesh_handle::handle_hypercube_uniform_default<mesh_class> (eclass, level, sc_MPI_COMM_WORLD, true,
+                                                                            true, false);
   EXPECT_TRUE (element_class::has_face_neighbor_cache ());
 
-  if (mesh.get_num_local_elements () == 0) {
+  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] };
+    = { &((*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) {
+  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 ();