diff --git a/tutorials/CMakeLists.txt b/tutorials/CMakeLists.txt index 4c21e232db..79d631bbb5 100644 --- a/tutorials/CMakeLists.txt +++ b/tutorials/CMakeLists.txt @@ -83,4 +83,7 @@ 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 ) endif() + diff --git a/tutorials/mesh_handle/t8_mesh_step3_adapt_mesh.cxx b/tutorials/mesh_handle/t8_mesh_step3_adapt_mesh.cxx new file mode 100644 index 0000000000..026988d85c --- /dev/null +++ b/tutorials/mesh_handle/t8_mesh_step3_adapt_mesh.cxx @@ -0,0 +1,116 @@ +/* + 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 /** General t8code header. Always include this. */ +#include /** General Mesh header. Always needed for mesh_handle code. */ +#include /** Competence Pack for basic mesh_handle features. Look into tutorials/mesh_handle/t8_mesh_competences for more information. */ +#include /** Wrapper for basic Cmesh to mesh_handle conversions. */ +#include /** Used to export mesh to vtk files. */ +#include +#include /** t8 vector dataclass. */ +#include "t8_mesh_tutorials_common.hxx" /** Default adaption function. */ +#include +#include + +/** 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 +std::unique_ptr +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 (level, comm); + /* Defining the adaption parameters. */ + struct adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 }; + mesh->set_balance (); + mesh->set_partition (); + /* Adapting once with our adapt_callback function. */ + mesh->set_adapt ( + TMeshClass::template mesh_adapt_callback_wrapper (default_adapt_callback, adapt_params)); + mesh->set_ghost (); + 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 (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Hello, this is the mesh adaptation example of t8code using the mesh handle.\n"); + t8_global_productionf (" [tutorial] 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 (" [tutorial] \n"); + + using mesh_type = t8_mesh_handle::mesh<>; + + t8_global_productionf (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Creating an adapted mesh.\n"); + t8_global_productionf (" [tutorial] \n"); + /* The initial uniform refinement level. */ + int uniform_level = 3; + /* Building the mesh. */ + { /** Scope to ensure mesh is deleted properly. */ + auto mesh = build_mesh (comm, uniform_level); + /* Write the mesh to a vtu file. */ + t8_global_productionf (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Writing adapted mesh to vtu file: step3_adapted_mesh.vtu\n"); + t8_global_productionf (" [tutorial] \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; +} diff --git a/tutorials/mesh_handle/t8_mesh_step4_partition_balance_ghost.cxx b/tutorials/mesh_handle/t8_mesh_step4_partition_balance_ghost.cxx new file mode 100644 index 0000000000..4569d3b514 --- /dev/null +++ b/tutorials/mesh_handle/t8_mesh_step4_partition_balance_ghost.cxx @@ -0,0 +1,197 @@ +/* + 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 /** General t8code header. Always include this. */ +#include /** General Mesh header. Always needed for mesh_handle code. */ +#include /** Used to export mesh to vtk files. */ +#include /** Wrapper for basic Cmesh to mesh_handle conversions. */ +#include +#include /** t8 vector dataclass. */ +#include "t8_mesh_tutorials_common.hxx" /** Default adaption function. */ +#include +#include + +/** 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, 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; + } +} + +/** 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 (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Hello, this is the mesh adaptation example of t8code using the mesh handle.\n"); + t8_global_productionf (" [tutorial] In this example we will Us\n"); + t8_global_productionf (" [tutorial] \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 }; + + using mesh_type = t8_mesh_handle::mesh<>; + + /** + * INITIAL MESH + */ + + t8_global_productionf (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Creating initial mesh.\n"); + t8_global_productionf (" [tutorial] \n"); + + /* Creating the initial mesh with uniform refinement. */ + auto mesh = t8_mesh_handle::handle_hypercube_hybrid_uniform_default (uniform_level, comm); + + /* Committing the initial mesh. */ + mesh->commit (); + + /* 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 (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Creating adapted mesh.\n"); + t8_global_productionf (" [tutorial] \n"); + + /* Creating the adapted mesh as a copy of the initial mesh (Initial mesh can't be refined because it is already committed.) */ + auto mesh_adapt = std::make_unique (*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 (&default_adapt_callback, adapt_params)); + /* Committing the adapted mesh. */ + mesh_adapt->commit (); + + /* 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 (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Creating partitioned and balanced mesh.\n"); + t8_global_productionf (" [tutorial] \n"); + + /* Creating the partition and balance mesh as a copy of the adapted mesh. */ + auto mesh_partition_balance = std::make_unique (*mesh_adapt); + + /* 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 (); + + /* 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 (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Creating ghost mesh.\n"); + t8_global_productionf (" [tutorial] \n"); + + /* Creating the ghost mesh as a copy of the partitioned and balanced mesh. */ + auto mesh_ghost = std::make_unique (*mesh_partition_balance); + + /* Creating the ghost layers. */ + mesh_ghost->set_ghost (); + + /* Committing the ghost mesh. */ + mesh_ghost->commit (); + + /* 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 (" [tutorial] \n"); + t8_global_productionf (" [tutorial] Finished all steps successfully.\n"); + t8_global_productionf (" [tutorial] \n"); + + sc_finalize (); + mpiret = sc_MPI_Finalize (); + SC_CHECK_MPI (mpiret); + return 0; +} diff --git a/tutorials/mesh_handle/t8_mesh_element_data.cxx b/tutorials/mesh_handle/t8_mesh_step5_element_data.cxx similarity index 80% rename from tutorials/mesh_handle/t8_mesh_element_data.cxx rename to tutorials/mesh_handle/t8_mesh_step5_element_data.cxx index 03249f0002..1bc8161d85 100644 --- a/tutorials/mesh_handle/t8_mesh_element_data.cxx +++ b/tutorials/mesh_handle/t8_mesh_step5_element_data.cxx @@ -21,18 +21,26 @@ */ /** \file t8_mesh_element_data.cxx - * This is the same as general/t8_step5_element_data.cxx but using the mesh handle interface instead of the forest + * This is step5 of the t8code tutorials. + * Therefor, this is the same as general/t8_step5_element_data.cxx but using the mesh handle interface instead of the forest * interface. + * In the following we will store data in the individual elements of our mesh. + * To do this, we will again create a uniform mesh, which will get adapted as in step4, + * with the difference that we partition, balance and create ghost elements all in the same step. + * After adapting the mesh we will learn how to build a data array and gather data for + * the local elements. Furthermore, we exchange the data values of the ghost elements and + * output the volume data to vtu. */ -#include +#include /** General t8code header. Always include this. */ -#include -#include -#include -#include +#include /** General Mesh header. Always needed for mesh_handle code. */ +#include /** Competence Pack for basic mesh_handle features. Look into tutorials/mesh_handle/t8_mesh_competences for more information. */ +#include /** Wrapper for basic Cmesh to mesh_handle conversions. */ +#include /** Used to export mesh to vtk files. */ #include -#include +#include /** t8 vector dataclass. */ +#include "t8_mesh_tutorials_common.hxx" /** Default adaption function. */ #include #include @@ -44,41 +52,6 @@ struct data_per_element_type double volume; /**< Volume of the element. */ }; -/** User data type we will pass to the adapt callback. */ -struct user_data -{ - t8_3D_vec midpoint; /**< The midpoint of our sphere. */ - double refine_if_inside_radius; /**< If an element's center is smaller than this value, we refine the element. */ - double coarsen_if_outside_radius; /**< If an element's center is larger this value, we coarsen its family. */ -}; - -/** The adaptation callback function. This will refine elements inside of a given sphere and coarsen the elements - * outside of a given sphere. - * \tparam TMeshClass The mesh handle class. - * \param [in] mesh The mesh that should be adapted. - * \param [in] elements One element or a family of elements to consider for adaptation. - * \param [in] user_data The user data to be used during the adaptation process. - * \return 1 if the first entry in \a elements should be refined, - * -1 if the family \a elements shall be coarsened, - * 0 else. - */ -template -int -adapt_callback ([[maybe_unused]] const TMeshClass &mesh, std::span elements, - const user_data &user_data) -{ - auto element_centroid = elements[0].get_centroid (); - double dist = t8_dist (element_centroid, user_data.midpoint); - if (dist < user_data.refine_if_inside_radius) { - return 1; - } - // Check if we got a family and if yes, if we should coarsen. - if ((elements.size () > 1) && (dist > user_data.coarsen_if_outside_radius)) { - return -1; - } - return 0; -} - /** Build a mesh with initial uniform refinement level \a level which is adapted according to \ref adapt_callback, * partitioned and balanced afterwards, and ghost elements are set. * \tparam TMeshClass The mesh handle class. @@ -91,7 +64,7 @@ std::unique_ptr build_mesh (sc_MPI_Comm comm, int level) { auto mesh_handle = t8_mesh_handle::handle_hypercube_hybrid_uniform_default (level, comm); - struct user_data adapt_data = { + struct adapt_data adapt_params = { { 0.5, 0.5, 1 }, /* Midpoint of the sphere. */ 0.2, /* Refine if inside this radius. */ 0.4 /* Coarsen if outside this radius. */ @@ -100,7 +73,7 @@ build_mesh (sc_MPI_Comm comm, int level) mesh_handle->set_balance (); mesh_handle->set_partition (); mesh_handle->set_adapt ( - TMeshClass::template mesh_adapt_callback_wrapper (adapt_callback, adapt_data)); + TMeshClass::template mesh_adapt_callback_wrapper (&default_adapt_callback, adapt_params)); mesh_handle->set_ghost (); mesh_handle->commit (); return mesh_handle; diff --git a/tutorials/mesh_handle/t8_mesh_tutorials_common.hxx b/tutorials/mesh_handle/t8_mesh_tutorials_common.hxx new file mode 100644 index 0000000000..0ce7605756 --- /dev/null +++ b/tutorials/mesh_handle/t8_mesh_tutorials_common.hxx @@ -0,0 +1,80 @@ +/* + 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 default_adapt_callback.hxx + * This is the default adaptation callback function that can be used to refine and coarsen a mesh in a spherical shape around a given point. + * It is used in step 3, 4 and 5 in the mesh_handle tutorials. + */ + +#pragma once + +#include /** General t8code header. Always include this. */ + +#include /** Mesh concepts header. */ +#include /** t8 vector dataclass. */ +#include + +/** The data that determines the adaptation characteristics of our algorithm. + * In this example we want to adapt in a spherical shape around a given point. */ +struct adapt_data +{ + t8_3D_vec midpoint; /**< midpoint of our sphere. */ + double refine_radius; /**< We refine inside this radius of our sphere.*/ + double coarsen_radius; /**< We coarsen outside this radius of our sphere. */ +}; + +/** + * Exemplary adaption callback function for the mesh handle. + * + * This will refine elements inside of a given sphere and coarsen elements + * outside of a given sphere. + * + * \tparam mesh_type The mesh handle class. + * \param[in] mesh The mesh that should be adapted. + * \param[in] elements One element or a family of elements to consider. + * \param[in] adapt_data The user data used during adaptation. + * + * \return + * 1 if the first element should be refined, + * -1 if the family of elements should be coarsened, + * 0 otherwise. + */ +template +int +default_adapt_callback ([[maybe_unused]] const mesh_type& mesh, + std::span elements, const adapt_data& adapt_data) +{ + auto element_centroid = elements[0].get_centroid (); + + double dist = t8_dist (element_centroid, adapt_data.midpoint); + /**< When this if Statement returns true, we are inside the set radius of our "refinement Sphere" of our point and therefor need to refine. */ + if (dist < adapt_data.refine_radius) { + return 1; /**< Refine. */ + } + + /** Only coarsen if we actually have a complete family. */ + if ((elements.size () > 1) && (dist > adapt_data.coarsen_radius)) { + return -1; /**< Coarsen. */ + } + + return 0; /**< Do nothing. */ +}