Improvement: Mesh handle tutorials

tutorials/CMakeLists.txt

@@ -82,5 +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_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/t8_mesh_step3_adapt_mesh.cxx

@@ -0,0 +1,113 @@
+/*
+  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 cubes.
+ * 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/competence_pack.hxx> /** Competence Pack for basic mesh_handle features. Look into tutorials/mesh_handle/t8_mesh_competences for more information. */
+#include <mesh_handle/constructor_wrappers.hxx> /** Wrapper for basic Cmesh to mesh_handle conversions. */
+#include <mesh_handle/mesh_io.hxx>              /** Used to export mesh to vtk files. */
+#include <mesh_handle/concepts.hxx> /** Include this to use c++ concepts related to the mesh handle. This can be used to constraint 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 our \ref adapt_callback function.
+ * \tparam TMeshClass    The mesh handle class.
+ * \param sc_MPI_Comm    The MPI Communicator.
+ * \param level          The initial uniform refinement level.
+ * \returns Unique pointer to the adapted mesh.
+ */
+template <t8_mesh_handle::T8MeshType TMeshClass>
+std::unique_ptr<TMeshClass>
+build_mesh (sc_MPI_Comm comm, int level)
+{
+  /* Generate a hybrid hypercube, made out of cubes, prisms etc. */
+  auto mesh = t8_mesh_handle::handle_hypercube_hybrid_uniform_default<TMeshClass> (level, comm);
+  /* Defining the adaption parameters. */
+  adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };
+  /* Adapting once with our adapt_callback function. */
+  mesh->set_adapt (
+    TMeshClass::template mesh_adapt_callback_wrapper<adapt_data> (default_adapt_callback<TMeshClass>, adapt_params));
+  mesh->commit ();
+  return mesh;
+}
+
+/** Entry point of the program. */
+int
+main (int argc, char **argv)
+{
+  /*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 (" [t8 step 3 Mesh handle] \n");
+  t8_global_productionf (
+    " [t8 step 3 Mesh handle] Hello, this is the mesh adaptation example of t8code using the mesh handle.\n");
+  t8_global_productionf (
+    " [t8 step 3 Mesh handle] In this example 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 (" [t8 step 3 Mesh handle] \n");
+
+  using mesh_type = t8_mesh_handle::mesh<>;
+
+  t8_global_productionf (" [t8 step 3 Mesh handle] \n");
+  t8_global_productionf (" [t8 step 3 Mesh handle] Creating an adapted mesh.\n");
+  t8_global_productionf (" [t8 step 3 Mesh handle] \n");
+  /* The initial uniform refinement level. */
+  int uniform_level = 3;
+  /* Building the mesh. */
+  { /** Scope to ensure mesh is deleted properly. */
+    auto mesh = build_mesh<mesh_type> (comm, uniform_level);
+    /* Write the mesh to a vtu file. */
+    t8_global_productionf (" [t8 step 3 Mesh handle] \n");
+    t8_global_productionf (" [t8 step 3 Mesh handle] Writing adapted mesh to vtu file: step3_adapted_mesh.vtu\n");
+    t8_global_productionf (" [t8 step 3 Mesh handle] \n");
+    t8_mesh_handle::write_mesh_to_vtk (*mesh, "step3_adapted_mesh.vtu");
+  }
+  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,239 @@
+/*
+  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_element_data.cxx
+ * This is step4 of the t8code mesh handle tutorials.
+ * Therefor, 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 control the mesh creation in more detail,
+ * how to partition and balance a mesh and how to generate a layer of ghost elements.
+ */
+
+#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 constraint the template parameters to only allow mesh handle classes. */
+#include <t8_types/t8_vec.hxx>      /** t8 vector dataclass. */
+#include "t8_mesh_tutorials_common.hxx" /** Default adaption function. */
+#include <memory>
+#include <iostream>
+
+using mesh_type = t8_mesh_handle::mesh<>; /**< To simplify the Code. */
+
+/** Helper function to print the total number of elements in the mesh after each step.
+ *  \param mesh  The mesh handle to get the number of elements from.
+ *  \param stage The stage of the mesh (e.g. "Initial mesh", "Adapted mesh", etc.) to print in the output.
+ *  \param comm  The MPI communicator to use for the reduction and printing.
+*/
+void
+print_mesh_stats (const std::unique_ptr<mesh_type>& mesh, const char* stage, sc_MPI_Comm comm)
+{
+  int local_elements = mesh->get_num_local_elements ();
+  int global_elements = 0;
+  MPI_Allreduce (&local_elements, &global_elements, 1, MPI_INT, MPI_SUM, comm);
+
+  int rank = 0;
+  MPI_Comm_rank (comm, &rank);
+  if (rank == 0) {
+    std::cout << "=== " << stage << " ===" << std::endl;
+    std::cout << "Total elements: " << global_elements << std::endl;
+  }
+}
+
+/** Helper function to create an adapted mesh from an initial mesh.
+ *  \param mesh  The initial mesh to adapt.
+ *  \param adapt_params  The adaptation parameters to use for the adaptation.
+ *  \return A unique pointer to the adapted mesh.
+*/
+std::unique_ptr<mesh_type>
+create_adapted_mesh (const std::unique_ptr<mesh_type>& mesh, const adapt_data& adapt_params)
+{
+  /* Creating the adapted mesh as a copy of the given mesh*/
+  auto mesh_adapt = std::make_unique<mesh_type> (*mesh);
+
+  /* Adapting the mesh once with our adapt_callback function from step 3 and the parameters defined above. */
+  mesh_adapt->set_adapt (
+    mesh_type::template mesh_adapt_callback_wrapper<adapt_data> (&default_adapt_callback<mesh_type>, adapt_params));
+  /* Committing the adapted mesh. */
+  mesh_adapt->commit ();
+
+  return mesh_adapt;
+}
+
+/** Helper function to create a partitioned and balanced mesh from an initial mesh.
+ *  \param mesh  The initial mesh to adapt.
+ *  \param adapt_params  The adaptation parameters to use for the adaptation.
+ *  \return A unique pointer to the partitioned and balanced mesh.
+*/
+std::unique_ptr<mesh_type>
+create_partitioned_balanced_mesh (const std::unique_ptr<mesh_type>& mesh)
+{
+  /* Creating the partition and balance mesh as a copy of the given mesh. */
+  auto mesh_partition_balance = std::make_unique<mesh_type> (*mesh);
+
+  /* Partitioning the mesh.*/
+  mesh_partition_balance->set_partition ();
+
+  /* Balancing the mesh. */
+  mesh_partition_balance->set_balance ();
+
+  /* Committing the partitioned and balanced mesh. */
+  mesh_partition_balance->commit ();
+
+  return mesh_partition_balance;
+}
+
+/** Helper function to create a ghost mesh from an initial mesh.
+ *  \param mesh  The initial mesh to adapt.
+ *  \return A unique pointer to the new mesh with ghost layers.
+*/
+std::unique_ptr<mesh_type>
+create_ghost_mesh (const std::unique_ptr<mesh_type>& mesh)
+{
+  /* Creating the ghost mesh as a copy of the given mesh. */
+  auto mesh_ghost = std::make_unique<mesh_type> (*mesh);
+
+  /* Creating the ghost layers. */
+  mesh_ghost->set_ghost ();
+
+  /* Committing the ghost mesh. */
+  mesh_ghost->commit ();
+
+  return mesh_ghost;
+}
+
+/** Entry point of the program. */
+int
+main (int argc, char** argv)
+{
+
+  /* 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 (" [t8 step 4 Mesh handle] \n");
+  t8_global_productionf (
+    " [t8 step 4 Mesh handle] Hello, this is the mesh adaptation example of t8code using the mesh handle.\n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] In this example we will Us\n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+
+  /* The initial uniform refinement level. */
+  int uniform_level = 3;
+
+  /* Parameters for the adaption step. */
+  struct adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };
+
+  /**
+     * INITIAL MESH
+    */
+
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] Creating initial mesh.\n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+
+  /* 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_mesh_stats (mesh, "Initial mesh", comm);
+
+  /* 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, "initial_mesh.vtu", 0, nullptr, true, true, true, true, true, false,
+                                         false);
+
+  /** 
+     * ADAPTED MESH
+    */
+
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] Creating adapted mesh.\n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+
+  /** Call creation function. */
+  auto mesh_adapt = create_adapted_mesh (mesh, adapt_params);
+
+  /* Printing the mesh information. */
+  print_mesh_stats (mesh_adapt, "Adapted mesh", comm);
+
+  /* Writing the mesh to vtu and pvtu files using the extended version of the function. */
+  t8_mesh_handle::write_mesh_to_vtk_ext (*mesh_adapt, "adapted_mesh.vtu", 0, nullptr, true, true, true, true, true,
+                                         false, false);
+
+  /**
+     * PARTITIONED, BALANCED MESH
+    */
+
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] Creating partitioned and balanced mesh.\n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+
+  /** Adapting the mesh from above a second time to see a difference when balancing. */
+  auto mesh_adapt_second = create_adapted_mesh (mesh_adapt, adapt_params);
+
+  /** Call creation function. */
+  auto mesh_partition_balance = create_partitioned_balanced_mesh (mesh_adapt_second);
+
+  /* Printing the mesh information. */
+  print_mesh_stats (mesh_partition_balance, "Partitioned and Balanced mesh", comm);
+
+  /* Writing the mesh to vtu and pvtu files using the extended version of the function. */
+  t8_mesh_handle::write_mesh_to_vtk_ext (*mesh_partition_balance, "partition_balance_mesh.vtu", 0, nullptr, true, true,
+                                         true, true, true, false, false);
+
+  /**
+     * GHOST MESH
+    */
+
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] Creating ghost mesh.\n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+
+  /** Call creation function. */
+  auto mesh_ghost = create_ghost_mesh (mesh_partition_balance);
+
+  /* Printing the mesh information*/
+  print_mesh_stats (mesh_ghost, "Ghost mesh", comm);
+
+  /* Writing the mesh to vtu and pvtu files using the extended version of the function. */
+  t8_mesh_handle::write_mesh_to_vtk_ext (*mesh_ghost, "ghost_mesh.vtu", 0, nullptr, true, true, true, true, true, false,
+                                         false);
+
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] Finished all steps successfully.\n");
+  t8_global_productionf (" [t8 step 4 Mesh handle] \n");
+
+  sc_finalize ();
+  mpiret = sc_MPI_Finalize ();
+  SC_CHECK_MPI (mpiret);
+  return 0;
+}