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 (8ba48ac).
⚠️ Report is 27 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! :)

lenaploetzke · 2026-07-16T10:03:45Z

+  sc_MPI_Comm comm = sc_MPI_COMM_WORLD;
+
+  /* Print a starting message. */
+  t8_global_productionf (" [tutorial] \n");


We should also think of something different than "tutorial" here. Any ideas?

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 :)

lenaploetzke

Review adapt callback file

lenaploetzke · 2026-07-20T14:34:32Z

@@ -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<user_data> (adapt_callback<TMeshClass>, adapt_data));
+    TMeshClass::template mesh_adapt_callback_wrapper<adapt_data> (&default_adapt_callback<TMeshClass>, adapt_params));


Could you please explain shortly why the & is valid here? :) I am not saying that it is wrong, just wondering why i left it out and why it is fine this way.

In this case it's optional, because set_adapt() uses an std::function as it's "adapt_callback_type", when you use &default_... you transfer the function pointer to create the std::function, if you leave it out (default_...) c++ automatically converts this to a function pointer implicitly to create the std::function.
So essentially, it's just implicit vs explicit handover of the function pointer.
I just added it here when i implemented the adapt_callback as its own file, because i used it in the other 2 tutorials like this aswell, so it's uniform.

Nice, thank you for the explanation. In general, explicit coding is better in most cases, so yes, & is even better! :)

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.

lenaploetzke · 2026-08-06T13:33:45Z

-#include <mesh_handle/mesh_io.hxx>
-#include <mesh_handle/concepts.hxx>
-#include <t8_types/t8_vec.hxx>
+#include <mesh_handle/mesh.hxx>            /** General Mesh header. Always needed for mesh_handle code. */


Suggested change

#include <mesh_handle/mesh.hxx> /** General Mesh header. Always needed for mesh_handle code. */

#include <mesh_handle/mesh.hxx> /** General mesh header. Always needed for mesh_handle code. */

lenaploetzke · 2026-08-06T13:34:03Z

-#include <mesh_handle/concepts.hxx>
-#include <t8_types/t8_vec.hxx>
+#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. */


Suggested change

#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/competence_pack.hxx> /** Competence pack for basic mesh_handle features. Look into tutorials/mesh_handle/t8_mesh_competences for more information. */

lenaploetzke · 2026-08-06T13:34:13Z

-#include <t8_types/t8_vec.hxx>
+#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. */


Suggested change

#include <mesh_handle/constructor_wrappers.hxx> /** Wrapper for basic Cmesh to mesh_handle conversions. */

#include <mesh_handle/constructor_wrappers.hxx> /** Wrapper for basic cmesh to mesh_handle conversions. */

lenaploetzke · 2026-08-06T13:38:45Z

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


Suggested change

/** \file default_adapt_callback.hxx

/** \file t8_mesh_tutorials_common.hxx

lenaploetzke · 2026-08-06T13:39:19Z

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


Suggested change

t8_3D_vec midpoint; /**< midpoint of our sphere. */

t8_3D_vec midpoint; /**< Midpoint of our sphere. */

lenaploetzke · 2026-08-06T14:06:07Z

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


This tutorial throws errors...

lenaploetzke · 2026-08-06T14:07:16Z

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


Suggested change

* \param adapt_params The adaptation parameters to use for the adaptation.

lenaploetzke · 2026-08-06T14:08:23Z

+  /* Balancing the mesh. */
+  mesh_partition_balance->set_balance ();
+
+  /* Committing the partitioned and balanced mesh. */


Not really. set_balance does not really balance the mesh. This is done at commiting. I think you can adapt it if you understand my comment at step 3

lenaploetzke · 2026-08-06T14:08:37Z

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


Suggested change

* \return A unique pointer to the new mesh with ghost layers.

* \return A unique pointer to the new mesh with a ghost layer.

lenaploetzke · 2026-08-06T14:08:51Z

+  return mesh_partition_balance;
+}
+
+/** Helper function to create a ghost mesh from an initial mesh.


Suggested change

/** Helper function to create a ghost mesh from an initial mesh.

/** Helper function to create a mesh with ghosts from an initial mesh.

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

	#include <mesh_handle/mesh.hxx> /** General Mesh header. Always needed for mesh_handle code. */
	#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/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/constructor_wrappers.hxx> /** Wrapper for basic cmesh to mesh_handle conversions. */

	/** \file default_adapt_callback.hxx
	/** \file t8_mesh_tutorials_common.hxx

	t8_3D_vec midpoint; /*< midpoint of our sphere. /
	t8_3D_vec midpoint; /*< Midpoint of our sphere. /

	* \return A unique pointer to the new mesh with ghost layers.
	* \return A unique pointer to the new mesh with a ghost layer.

	/** Helper function to create a ghost mesh from an initial mesh.
	/** Helper function to create a mesh with ghosts from an initial mesh.

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!

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

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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 Aug 6, 2026 •

edited

Loading

lenaploetzke commented Jul 21, 2026 •

edited

Loading