Improvement: Mesh handle tutorials by Vyp3er · Pull Request #2348 · DLR-AMR/t8code

Vyp3er · 2026-06-22T08:40:12Z

Describe your changes here:

All these boxes must be checked by the AUTHOR before requesting review:

The PR is small enough to be reviewed easily. If not, consider splitting up the changes in multiple PRs.
The title starts with one of the following prefixes: Documentation:, Bugfix:, Feature:, Improvement: or Other:.
If the PR is related to an issue, make sure to link it.
The author made sure that, as a reviewer, he/she would check all boxes below.

All these boxes must be checked by the REVIEWERS before merging the pull request:

As a reviewer please read through all the code lines and make sure that the code is fully understood, bug free, well-documented and well-structured.

General

The reviewer executed the new code features at least once and checked the results manually.
The code follows the t8code coding guidelines.
New source/header files are properly added to the CMake files.
The code is well documented. In particular, all function declarations, structs/classes and their members have a proper doxygen documentation. Make sure to add a file documentation for each file!
README.md files are updated if necessary.
All new algorithms and data structures are sufficiently optimal in terms of memory and runtime (If this should be merged, but there is still potential for optimization, create a new issue).

Tests

The code is covered in an existing or new test case using Google Test.
The code coverage of the project (reported in the CI) should not decrease. If coverage is decreased, make sure that this is reasonable and acceptable.
Valgrind doesn't find any bugs in the new code. This script can be used to check for errors; see also this wiki article.

If the Pull request introduces code that is not covered by the github action (for example coupling with a new library):

Should this use case be added to the github action?
If not, does the specific use case compile and all tests pass (check manually).

Scripts and Wiki

If a new directory with source files is added, it must be covered by the scripts/internal/find_all_source_files.sh to check the indentation of these files.
If this PR introduces a new feature, it must be covered in an example or tutorial and a Wiki article.

License

The author added a BSD statement to doc/ (or already has one).

codecov · 2026-07-01T09:48:30Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.28%. Comparing base (66cd94f) to head (c411a76).
⚠️ Report is 33 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2348   +/-   ##
=======================================
  Coverage   82.28%   82.28%           
=======================================
  Files         125      125           
  Lines       20701    20701           
=======================================
  Hits        17033    17033           
  Misses       3668     3668

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

lenaploetzke

Partial review. Thank you for your work, this is really nice and my comments are mainly documentation! :)

Co-authored-by: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>

lenaploetzke · 2026-07-20T09:10:10Z

+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/** \file t8_mesh_element_data.cxx


Please adapt :)

Could you please adapt this?

lenaploetzke

Review adapt callback file

lenaploetzke · 2026-07-21T11:04:14Z

Could you please have a look at the failing workflows?
Please also make sure in the future to try your code once before committing.

lenaploetzke

Most things are just typos and capitalization.

Co-authored-by: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>

lenaploetzke · 2026-08-14T08:48:41Z

+  int rank = 0;
+  MPI_Comm_rank (comm, &rank);
+  if (rank == 0) {
+    std::cout << "=== " << stage << " ===" << std::endl;
+    std::cout << "Total elements: " << global_elements << std::endl;
+  }


Yeah i know, but some pverhead here. get_num_global_elements is merged now so you are ready to use it here :)

lenaploetzke · 2026-08-14T08:53:45Z

+#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. */


This line is too long and i think you can remove some line breaks in the file descriptions . If you want to i can show you how to add a helper for this in vscode :)

lenaploetzke · 2026-08-14T08:55:40Z

+
+/** 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.


Suggested change

* \param sc_MPI_Comm The MPI Communicator.

* \param comm The MPI Communicator.

lenaploetzke · 2026-08-14T08:57:32Z

+  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;


Suggested change

int uniform_level = 3;

const int uniform_level = 3;

Best way is to mark everything const if possible :)

lenaploetzke · 2026-08-14T08:59:15Z

+    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");


Would be better to introduce a variable for the name and reusing it! That way if you change the name, you do not have to change it everywhere :)

lenaploetzke · 2026-08-14T09:08:30Z

+  int uniform_level = 3;
+  /* Building the mesh. */
+  { /** Scope to ensure mesh is deleted properly. */
+    auto mesh = build_mesh<mesh_type> (comm, uniform_level);


I noticed that in the general tutorial, the uniform mesh is also stored as a vtk such that you can compare them. Why did you decided against this here?

lenaploetzke · 2026-08-14T09:10:52Z

+ * 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.


Suggested change

* 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.

* we will now learn how to partition and balance a mesh and how to generate a layer of ghost elements.

lenaploetzke · 2026-08-14T09:11:44Z

+#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. */


Also not "default" here. Just use the description that you provided in step 3 pls

lenaploetzke · 2026-08-14T09:12:10Z

+#include <t8_types/t8_vec.hxx>      /** t8 vector dataclass. */
+#include "t8_mesh_tutorials_common.hxx" /** Default adaption function. */
+#include <memory>
+#include <iostream>


Suggested change

#include <iostream>

lenaploetzke · 2026-08-14T09:25:02Z

+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;


I think i already wrote is somewhere but please use your new mesh handle function here (already merged)

lenaploetzke · 2026-08-14T09:26:00Z

+  t8_global_productionf (" [mesh_step4] Total elements: %i \n", global_elements);
+}
+
+/** Helper function to create an adapted mesh from an initial mesh.


Now you just adapt a mesh and dont create a new adapted mesh. Please change this

lenaploetzke · 2026-08-14T09:27:10Z

+  /* Adapting the mesh once 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::template mesh_adapt_callback_wrapper<adapt_data> (&adapt_callback_sphere<mesh_type>, adapt_params));
+  /* Committing the adapted mesh. */


Not really. The mesh gets adapted at the commit step, so its not "the adapted mesh"

lenaploetzke · 2026-08-14T09:27:24Z

+  mesh->commit ();
+}
+
+/** Helper function to create a partitioned and balanced mesh from an initial mesh.


Same as above

lenaploetzke · 2026-08-14T09:30:16Z

+void
+create_partitioned_balanced_mesh (const std::unique_ptr<mesh_type>& mesh)
+{
+  /* Calculate partition information.*/


Maybe it is good if you have a look at the documentation of these functions and of commit. You do not calculate something, just setting the flags such that the mesh is partitioned at commit call. We can also talk about the commit procedure if you want to, just ask.

lenaploetzke · 2026-08-14T09:56:54Z

+  t8_global_productionf (" [mesh_step4] \n");
+
+  /* The initial uniform refinement level. */
+  int uniform_level = 3;


Suggested change

int uniform_level = 3;

const int uniform_level = 3;

lenaploetzke · 2026-08-14T09:58:11Z

+  int uniform_level = 3;
+
+  /* Parameters for the adaption step. */
+  struct adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };


Suggested change

struct adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };

adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };

The struct is old c style

lenaploetzke · 2026-08-14T10:02:17Z

+                                           true, false, false);
+
+    /**
+   * GHOST MESH


At comments you have to pay attention to the indention please,this is not checked by the ci and not corrected by the indent script

lenaploetzke · 2026-08-14T10:20:05Z

+    create_ghost_mesh (mesh);
+
+    /* Printing the mesh information. */
+    print_mesh_stats (mesh, "Ghost mesh", comm);


Maybe it would be nice to print also the number of ghost elements here (maybe only for one process or so).

lenaploetzke · 2026-08-14T10:22:36Z

 {
  auto mesh_handle = t8_mesh_handle::handle_hypercube_hybrid_uniform_default<TMeshClass> (level, comm);
-  struct user_data adapt_data = {
+  struct adapt_data adapt_params = {


Suggested change

struct adapt_data adapt_params = {

adapt_data adapt_params = {

I also just copied the old C style whoopsi

Schmitt added 5 commits June 19, 2026 09:37

First Changes and File Creation

05c741b

Spellchecking correct

53199cb

Mesh_handle_tutorial Step3

665d24c

Mesh_handle_tutorial Step3

9523fc5

Mesh_handle_tutorial Step3 fixed and Step4 added.

604e003

Vyp3er changed the title ~~Mesh handle tutorials~~ Improvement: Mesh handle tutorials Jul 1, 2026

added bsd license

282f592

Vyp3er marked this pull request as ready for review July 1, 2026 08:46

Merge remote-tracking branch 'origin/main' into mesh_handle_tutorials

9f7696b

lenaploetzke self-requested a review July 1, 2026 08:52

lenaploetzke self-assigned this Jul 1, 2026

spell checking corrected

bd84430

lenaploetzke reviewed Jul 16, 2026

View reviewed changes

Vyp3er and others added 5 commits July 17, 2026 09:45

Merge branch 'main' into mesh_handle_tutorials

ff4aa99

Apply suggestion from @lenaploetzke

d0dc470

Co-authored-by: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>

Documentation Changes and Renaming

ca472bd

added documentation and comments

9896011

Added Scope into main to prevent deletion Error

a05095c

lenaploetzke reviewed Jul 20, 2026

View reviewed changes

Integrated Review and cleaned up the comments.

bfe57f8

lenaploetzke reviewed Jul 20, 2026

View reviewed changes

Schmitt added 2 commits July 20, 2026 16:40

Adapted to comments.

b79b1d6

renamed element data tutorial to step 5

7b316f3

lenaploetzke reviewed Jul 21, 2026

View reviewed changes

lenaploetzke assigned Vyp3er and unassigned lenaploetzke Jul 22, 2026

Fixed Pull Requested changes

8ba48ac

Vyp3er assigned lenaploetzke Aug 6, 2026

lenaploetzke requested changes Aug 6, 2026

View reviewed changes

lenaploetzke removed their assignment Aug 6, 2026

Vyp3er and others added 2 commits August 10, 2026 13:43

Apply suggestions from code review

0d60c0e

Co-authored-by: lenaploetzke <70579874+lenaploetzke@users.noreply.github.com>

Fixed errors marked in pull request

c411a76

Vyp3er assigned lenaploetzke and unassigned Vyp3er Aug 10, 2026

change print labels

4ab1785

lenaploetzke reviewed Aug 14, 2026

View reviewed changes

lenaploetzke assigned Vyp3er and unassigned lenaploetzke Aug 14, 2026

	* \param sc_MPI_Comm The MPI Communicator.
	* \param comm The MPI Communicator.

		* 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.

	* 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.
	* we will now learn how to partition and balance a mesh and how to generate a layer of ghost elements.

	struct adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };
	adapt_data adapt_params = { { 0.5, 0.5, 1.0 }, 0.2, 0.4 };

	struct adapt_data adapt_params = {
	adapt_data adapt_params = {

Uh oh!

Conversation

Vyp3er commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

General

Tests

Scripts and Wiki

License

Uh oh!

codecov Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

lenaploetzke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lenaploetzke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lenaploetzke commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lenaploetzke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Vyp3er commented Jun 22, 2026 •

edited

Loading

codecov Bot commented Jul 1, 2026 •

edited

Loading

lenaploetzke commented Jul 21, 2026 •

edited

Loading