Improvement: Mesh handle tutorials

tutorials/CMakeLists.txt

@@ -82,6 +82,8 @@ copy_tutorial_file (features/t8_features_curved_meshes_generate_cmesh_tet.geo)
 copy_tutorial_file (features/t8_features_curved_meshes_generate_cmesh_tri.geo)
 
 if( T8CODE_BUILD_MESH_HANDLE )
-    add_mesh_handle_tutorial( NAME t8_mesh_element_data SOURCES mesh_handle/t8_mesh_element_data.cxx )
     add_mesh_handle_tutorial( NAME t8_mesh_step2_uniform_mesh SOURCES mesh_handle/t8_mesh_step2_uniform_mesh.cxx )
+    add_mesh_handle_tutorial( NAME t8_mesh_step3_adapt_mesh SOURCES mesh_handle/t8_mesh_step3_adapt_mesh.cxx )
+    add_mesh_handle_tutorial( NAME t8_mesh_step4_partition_balance_ghost SOURCES mesh_handle/t8_mesh_step4_partition_balance_ghost.cxx )
+    add_mesh_handle_tutorial( NAME t8_mesh_step5_element_data SOURCES mesh_handle/t8_mesh_step5_element_data.cxx )
 endif()

tutorials/mesh_handle/README.md

@@ -17,13 +17,13 @@ Initialize t8code and print a welcome message.
 [step1](https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh) - 
 Create a coarse mesh, output it to vtu and destroy it. We need a coarse mesh to initialize our mesh handle mesh. 
 
-[step2] -  
+[step2] (mesh_handle/t8_mesh_step2_uniform_mesh.cxx) -   
 Create a uniform mesh, get its number of local and global elements and output it to vtu.
 
-[step3] - 
+[step3] (mesh_handle/t8_mesh_step3_adapt_mesh.cxx) - 
 Adapt a mesh according to a user-defined criterion. 
 
-[step4] - 
+[step4] (mesh_handle/t8_mesh_step4_partition_balance_ghost.cxx) - 
 Partitioning, balancing and creating a ghost layer for a mesh.
 
 [step5](mesh_handle/t8_mesh_step5_element_data.cxx) - 

tutorials/mesh_handle/t8_mesh_step3_adapt_mesh.cxx

@@ -0,0 +1,121 @@
+/*
+  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 types 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 t8_mesh_step3_adapt_mesh.cxx
+ * This is step3 of the t8code mesh handle tutorials.
+ * Therefore, this is the same as general/t8_step3_adapt_forest.cxx but using the mesh handle interface instead of the forest
+ * interface.
+ * After generating a coarse mesh (step1) and building a uniform mesh
+ * on it (step2), we will now adapt (= refine and coarsen) the mesh
+ * according to our own criterion.
+ *
+ * The geometry (coarse mesh) is again a cube, this time modelled with
+ * 6 tetrahedra, 6 prisms and 4 hexahedra.
+ * We refine an element if its midpoint is within a sphere of given radius
+ * around the point (0.5, 0.5, 1) and we coarsen outside of a given radius.
+ * We will use non-recursive refinement, that means that the refinement level
+ * of any element will change by at most +-1.
+*/
+
+#include <t8.h>                                 /** General t8code header. Always include this. */
+#include <mesh_handle/mesh.hxx>                 /** General mesh header. Always needed for mesh_handle code. */
+#include <mesh_handle/mesh_io.hxx>              /** Used to export mesh to vtk files. */
+#include <mesh_handle/constructor_wrappers.hxx> /** Wrapper for basic cmesh to mesh_handle conversions. */
+#include <mesh_handle/concepts.hxx>             /** Include this to use c++ concepts related to the mesh handle. 
+                                          *  This can be used to constrain the template parameters to only allow mesh handle classes. */
+#include "t8_mesh_tutorials_common.hxx"         /** Adaption function definition used for this tutorial. */
+#include <memory>
+
+/** Build our adapted mesh by transferring the adaption parameters and adapting once with the adapt_callback_sphere function defined in \ref t8_mesh_tutorials_common.hxx.
+ * \tparam TMeshClass    The mesh handle class.
+ * \param [in] mesh      The mesh that should be adapted.
+ */
+template <t8_mesh_handle::T8MeshType TMeshClass>
+void
+step3_adapt_mesh (TMeshClass &mesh)
+{
+  /* Defining the adaption parameters. */
+  adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };
+  /** Adapting once using our adapt callback.
+   *  set_adapt() only records how the mesh should be changed, it does not modify anything yet. 
+   *  commit() is the function that actually builds the new, adapted mesh from these settings.
+   *  This "configure, then commit" split lets t8code carry out several mesh operations together in one efficient pass, rather than one at a time. 
+   */
+  mesh.set_adapt (
+    TMeshClass::template mesh_adapt_callback_wrapper<adapt_data> (&adapt_callback_sphere<TMeshClass>, adapt_params));
+  mesh.commit ();
+}
+
+/** Entry point of the program. */
+int
+main (int argc, char **argv)
+{
+  /* Set file names for vtk export. */
+  const char *prefix_initial = "step3_initial_uniform_mesh";
+  const char *prefix_adapted = "step3_adapted_mesh";
+  /* Initialize MPI. This has to happen before we initialize sc or t8code. */
+  int mpiret = sc_MPI_Init (&argc, &argv);
+  /* Error check the MPI return value. */
+  SC_CHECK_MPI (mpiret);
+  /* Initialize the sc library, has to happen before we initialize t8code. */
+  sc_init (sc_MPI_COMM_WORLD, 1, 1, NULL, SC_LP_ESSENTIAL);
+  /* Initialize t8code with log level SC_LP_PRODUCTION. See sc.h for more info on the log levels. */
+  t8_init (SC_LP_PRODUCTION);
+  /* We will use MPI_COMM_WORLD as a communicator. */
+  sc_MPI_Comm comm = sc_MPI_COMM_WORLD;
+
+  /* Print a starting message. */
+  t8_global_productionf (" [mesh_step3] \n");
+  t8_global_productionf (
+    " [mesh_step3] Hello, this is the mesh adaptation tutorial of t8code using the mesh handle.\n");
+  t8_global_productionf (
+    " [mesh_step3] In this tutorial we will adapt a mesh in a spherical shape around a given point "
+    "and write the adapted mesh to a vtu file.\n");
+  t8_global_productionf (" [mesh_step3] \n");
+
+  using mesh_type = t8_mesh_handle::mesh<>;
+
+  t8_global_productionf (" [mesh_step3] Creating an adapted mesh.\n");
+  t8_global_productionf (" [mesh_step3] \n");
+  /* The initial uniform refinement level. */
+  const int uniform_level = 3;
+  /* Building the mesh. */
+  { /* Scope to ensure mesh is deleted properly. */
+    /* Generate a hybrid hypercube, made out of hexahedra, prisms etc. */
+    auto mesh = t8_mesh_handle::handle_hypercube_hybrid_uniform_default<mesh_type> (uniform_level, comm);
+    /* Saving the initial mesh to vtu files to compare them later. */
+    t8_global_productionf (" [mesh_step3] Writing initial mesh to vtu files: %s*\n", prefix_initial);
+    t8_global_productionf (" [mesh_step3] \n");
+    t8_mesh_handle::write_mesh_to_vtk (*mesh, prefix_initial);
+
+    /* Call the function that handles the adaption. */
+    step3_adapt_mesh<mesh_type> (*mesh);
+    /* Write the mesh to a vtu file. */
+    t8_global_productionf (" [mesh_step3] Writing adapted mesh to vtu files: %s*\n", prefix_adapted);
+    t8_global_productionf (" [mesh_step3] \n");
+    t8_mesh_handle::write_mesh_to_vtk (*mesh, prefix_adapted);
+  }
+  sc_finalize ();
+  mpiret = sc_MPI_Finalize ();
+  SC_CHECK_MPI (mpiret);
+  return 0;
+}

tutorials/mesh_handle/t8_mesh_step4_partition_balance_ghost.cxx

@@ -0,0 +1,213 @@
+/*
+  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 types 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 t8_mesh_step4_partition_balance_ghost.cxx
+ * This is step4 of the t8code mesh handle tutorials.
+ * Therefore, this is the same as general/t8_step4_partition_balance_ghost.cxx but using the mesh handle interface instead of the forest 
+ * interface.
+ * After generating a coarse mesh (step1), building a uniform mesh
+ * on it (step2) and adapting this mesh (step3)
+ * we will now learn how to partition and balance a mesh and how to generate a layer of ghost elements. 
+ * Note: Normally, you would call set_adapt(), set_partition(), set_balance() and set_ghost() and then commit() only once, 
+ * as shown in step 5. commit() applies the operations in the correct order automatically, regardless of the order of the set_*() calls. 
+ * In this tutorial, we commit after each operation instead, so that we can see what each of them does and 
+ * compare the resulting vtk files one after another.
+ */
+
+#include <t8.h>                                 /** General t8code header. Always include this. */
+#include <mesh_handle/mesh.hxx>                 /** General mesh header. Always needed for mesh_handle code. */
+#include <mesh_handle/mesh_io.hxx>              /** Used to export mesh to vtk files. */
+#include <mesh_handle/constructor_wrappers.hxx> /** Wrapper for basic cmesh to mesh_handle conversions. */
+#include <mesh_handle/concepts.hxx> /** Include this to use c++ concepts related to the mesh handle. This can be used to constrain the template parameters to only allow mesh handle classes. */
+#include <t8_types/t8_vec.hxx>      /** t8 vector dataclass. */
+#include "t8_mesh_tutorials_common.hxx" /** Adaption function definition used for this tutorial. */
+#include <memory>
+
+using mesh_type = t8_mesh_handle::
+  mesh<>; /**< Mesh class used in this tutorial. We define it globally to get rid of the function templates to simplify the code. */
+
+/** Helper function to print the total number of elements in the mesh after each step.
+ *  \param [in] mesh  The mesh handle to get the number of elements from.
+ *  \param [in] stage The stage of the mesh (e.g. "Initial mesh", "Adapted mesh", etc.) to print in the output.
+ *  \param [in] prefix The prefix for the filename of the exported vtk files. 
+*/
+void
+print_stats_and_export (mesh_type& mesh, const char* stage, const char* prefix)
+{
+  t8_locidx_t local_elements = mesh.get_num_local_elements ();
+  t8_gloidx_t global_elements = mesh.get_num_global_elements ();
+
+  t8_global_productionf (" [mesh_step4] === %s === \n", stage);
+  t8_global_productionf (" [mesh_step4] Local elements on the root process: %i \n", local_elements);
+  t8_global_productionf (" [mesh_step4] Total elements: %li \n", global_elements);
+
+  /* Writing the mesh to vtu and pvtu files, using the extended version of the function to ensure additional data like ghost elements, treeid etc. to be written into the files. */
+  t8_mesh_handle::write_mesh_to_vtk_ext (mesh, prefix, 0, nullptr, true, true, true, true, true, false, false);
+}
+
+/** Helper function to adapt a given mesh using the predefined adaption callback function.
+ *  \param [in] mesh  The initial mesh to adapt.
+ *  \param [in] adapt_params  The adaptation parameters to use for the adaptation.
+*/
+
+void
+step4_adapt_mesh (mesh_type& mesh, const adapt_data& adapt_params)
+{
+  /* Setting the adapt-flag with our adapt_callback_sphere function from step 3 and the adapt_params. Both can be found in the file \ref t8_mesh_tutorials_common.hxx. */
+  mesh.set_adapt (mesh_type::mesh_adapt_callback_wrapper<adapt_data> (&adapt_callback_sphere<mesh_type>, adapt_params));
+  /* Committing the mesh. */
+  mesh.commit ();
+}
+
+/** Helper function to partition and balance a given mesh.
+ *  \param [in] mesh  The initial mesh to partition and balance.
+*/
+
+void
+step4_partition_balance_mesh (mesh_type& mesh)
+{
+  /* Setting partition flag.*/
+  mesh.set_partition ();
+
+  /* Setting balancing flag. */
+  mesh.set_balance ();
+
+  /* Committing the mesh. */
+  mesh.commit ();
+}
+
+/** Helper function to add a layer of ghost elements to an initial mesh.
+ *  \param [in] mesh  The initial mesh to add the ghost elements to.
+*/
+void
+step4_ghost_mesh (mesh_type& mesh)
+{
+  /* Set flag such that ghost layer is created on commit. */
+  mesh.set_ghost ();
+
+  /* Committing the mesh. */
+  mesh.commit ();
+}
+
+/** Entry point of the program. */
+int
+main (int argc, char** argv)
+{
+  /* Setting the file prefixes for the vtk files. */
+  const char* prefix_initial = "step4_initial_mesh";
+  const char* prefix_adapt = "step4_adapted_mesh";
+  const char* prefix_partition_balance = "step4_partitioned_balanced_mesh";
+  const char* prefix_ghost = "step4_ghost_mesh";
+  /* Initialize MPI. This has to happen before we initialize sc or t8code. */
+  int mpiret = sc_MPI_Init (&argc, &argv);
+  /* Error check the MPI return value. */
+  SC_CHECK_MPI (mpiret);
+  /* Initialize the sc library, has to happen before we initialize t8code. */
+  sc_init (sc_MPI_COMM_WORLD, 1, 1, NULL, SC_LP_ESSENTIAL);
+  /* Initialize t8code with log level SC_LP_PRODUCTION. See sc.h for more info on the log levels. */
+  t8_init (SC_LP_PRODUCTION);
+  /* We will use MPI_COMM_WORLD as a communicator. */
+  sc_MPI_Comm comm = sc_MPI_COMM_WORLD;
+
+  /* Print a starting message. */
+  t8_global_productionf (" [mesh_step4] \n");
+  t8_global_productionf (" [mesh_step4] Hello, this is step 4 of the t8code mesh_handle tutorials.\n");
+  t8_global_productionf (" [mesh_step4] In this example we will create a mesh, adapt, partition, balance "
+                         "and create a ghost layer on it. \n");
+  t8_global_productionf (" [mesh_step4] \n");
+
+  /* The initial uniform refinement level. */
+  const int uniform_level = 3;
+
+  /* Parameters for the adaption step. */
+  adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };
+
+  /**
+   * INITIAL MESH
+  */
+
+  t8_global_productionf (" [mesh_step4] \n");
+  t8_global_productionf (" [mesh_step4] Creating initial mesh.\n");
+  t8_global_productionf (" [mesh_step4] \n");
+  { /** Mesh scope begin. */
+    /* Creating the initial mesh with uniform refinement. */
+    auto mesh = t8_mesh_handle::handle_hypercube_hybrid_uniform_default<mesh_type> (uniform_level, comm);
+
+    /* Printing the mesh information. */
+    print_stats_and_export (*mesh, "Initial mesh", prefix_initial);
+
+    /** 
+     * ADAPT MESH
+     */
+
+    t8_global_productionf (" [mesh_step4] \n");
+    t8_global_productionf (" [mesh_step4] Adapt the mesh.\n");
+    t8_global_productionf (" [mesh_step4] \n");
+
+    /** Call adaption helper function. */
+    step4_adapt_mesh (*mesh, adapt_params);
+
+    /* Printing the mesh information. */
+    print_stats_and_export (*mesh, "Adapted mesh", prefix_adapt);
+
+    /**
+     * PARTITION, BALANCE MESH
+     */
+
+    t8_global_productionf (" [mesh_step4] \n");
+    t8_global_productionf (" [mesh_step4] Partition and balance the mesh.\n");
+    t8_global_productionf (" [mesh_step4] \n");
+
+    /** Adapting the mesh from above a second time to see a difference when balancing. */
+    step4_adapt_mesh (*mesh, adapt_params);
+
+    /** Call partitioning and balancing helper function. */
+    step4_partition_balance_mesh (*mesh);
+
+    /* Printing the mesh information. */
+    print_stats_and_export (*mesh, "Partitioned and Balanced mesh", prefix_partition_balance);
+
+    /**
+     * GHOST LAYER
+     */
+
+    t8_global_productionf (" [mesh_step4] \n");
+    t8_global_productionf (" [mesh_step4] Creating ghost layer for mesh.\n");
+    t8_global_productionf (" [mesh_step4] \n");
+
+    /** Call ghost helper function. */
+    step4_ghost_mesh (*mesh);
+
+    /* Printing the mesh information. */
+    print_stats_and_export (*mesh, "Ghost mesh", prefix_ghost);
+    int ghost_elements = mesh->get_num_ghosts ();
+    t8_global_productionf (" [mesh_step4] Number of ghost elements: %i \n", ghost_elements);
+
+    t8_global_productionf (" [mesh_step4] \n");
+    t8_global_productionf (" [mesh_step4] Finished all steps successfully.\n");
+    t8_global_productionf (" [mesh_step4] \n");
+  } /** Mesh scope end. */
+  sc_finalize ();
+  mpiret = sc_MPI_Finalize ();
+  SC_CHECK_MPI (mpiret);
+  return 0;
+}