Mesh competence tutorial by Vyp3er · Pull Request #2370 · DLR-AMR/t8code

Vyp3er · 2026-07-20T11:03:11Z

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

…rientation

codecov · 2026-07-20T11:51:27Z

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2370   +/-   ##
=======================================
  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

Nice tutorial! Maybe a bit more of explanation would help :)

lenaploetzke · 2026-08-07T08:35:00Z

+ * These so called competences are a way to extend the functionality of the mesh handle and its elements.
+ * 
+ * The competences are organized in different types, depending the functionality. 
+ * Element data competences are used to store data in the mesh elements and work with it in different ways


Suggested change

* Element data competences are used to store data in the mesh elements and work with it in different ways

* Element data competences are used to store data in the mesh elements and work with it in different ways.

lenaploetzke · 2026-08-07T08:35:48Z

+ * 
+ * The competences are organized in different types, depending the functionality. 
+ * Element data competences are used to store data in the mesh elements and work with it in different ways
+ * Cache competences are used to store data in the mesh elements to work with it more efficiently, e.g. to avoid recomputing the same data multiple times.


Suggested change

* Cache competences are used to store data in the mesh elements to work with it more efficiently, e.g. to avoid recomputing the same data multiple times.

* Cache competences are used to store data in the mesh elements to avoid recomputing the same data multiple times.

lenaploetzke · 2026-08-07T08:36:58Z

+
+#include <t8.h> /** General t8code header. Always include this. */
+
+#include <mesh_handle/mesh.hxx>                 /** General Mesh header, always needed for mesh_handle code. */


Please correct capitalization in all the descriptions pls

lenaploetzke · 2026-08-07T08:43:15Z

+ * Creating a simple custom competence that computes the squared volume of an element.
+ * 
+ * All custom competences follow the same CRTP inheritance pattern:
+ * They are templated on the underlying element type and inherit from 


Suggested change

* They are templated on the underlying element type and inherit from

* They are templated on the underlying element type TUnderlying and inherit from

lenaploetzke · 2026-08-07T08:45:41Z

+ * They are templated on the underlying element type and inherit from 
+ * t8_crtp_operator<TUnderlying, Competence>. This gives the competence access to the functionality
+ * of the underlying element with using this->underlying(), allowing it to extend the element with additional methods.
+ * The use of t8_crtp_operator also avoids diamond-shaped inheritance when multiple competences are combined into one pack. 


Suggested change

* The use of t8_crtp_operator also avoids diamond-shaped inheritance when multiple competences are combined into one pack.

I think we don't need this for the user. This would need some more explanation, i think we can leave it out

lenaploetzke · 2026-08-07T10:13:21Z

+   * We will now create a second mesh with our custom competence pack that includes the volume competence and our custom defined competence 'volume_squared'.
+  */
+    /* Defining a competence pack with the volume cache competence and our custom defined competence. */
+    using custom_element_competences = element_competence_pack<cache_volume, volume_squared_custom_competence>;


Can you also include the cache competences header?

lenaploetzke · 2026-08-07T10:14:01Z

+    using custom_element_competences = element_competence_pack<cache_volume, volume_squared_custom_competence>;
+
+    /* Defining a custom mesh_type with our competence pack. */
+    using custom_mesh = mesh<custom_element_competences>;


Suggested change

using custom_mesh = mesh<custom_element_competences>;

using custom_mesh_class = mesh<custom_element_competences>;

lenaploetzke · 2026-08-07T10:14:29Z

+                           level);
+    t8_global_productionf (" [t8 Step A Mesh handle] \n");
+
+    /* Creating a custom mesh with the mesh_type including our custom competence pack and the initial refinement level 2. */


Suggested change

/* Creating a custom mesh with the mesh_type including our custom competence pack and the initial refinement level 2. */

/* Creating a mesh with the mesh_type including our custom competence pack. */

lenaploetzke · 2026-08-07T10:14:43Z

+    t8_global_productionf (" [t8 Step A Mesh handle] \n");
+
+    /* Creating a custom mesh with the mesh_type including our custom competence pack and the initial refinement level 2. */
+    auto custom = handle_hypercube_hybrid_uniform_default<custom_mesh> (level, comm);


Suggested change

auto custom = handle_hypercube_hybrid_uniform_default<custom_mesh> (level, comm);

auto custom_mesh = handle_hypercube_hybrid_uniform_default<custom_mesh> (level, comm);

lenaploetzke · 2026-08-07T10:15:27Z

+    auto custom = handle_hypercube_hybrid_uniform_default<custom_mesh> (level, comm);
+
+    t8_global_productionf (" [t8 Step A Mesh handle] \n");
+    t8_global_productionf (" [t8 Step A Mesh handle] Demonstrating the custom competence 'Squared Value'.\n");


Suggested change

t8_global_productionf (" [t8 Step A Mesh handle] Demonstrating the custom competence 'Squared Value'.\n");

t8_global_productionf (" [t8 Step A Mesh handle] Demonstrating the custom competence 'squared volume'.\n");

Schmitt and others added 12 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

added bsd license

282f592

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

9f7696b

spell checking corrected

bd84430

Added get_reference_coordinates, element_is_equal, forest_leaf_face_o…

4042c00

…rientation

Added a tutorial to demonstrate the core competences of the mesh handle.

e796ce3

deleted unnecessary files.

6ac480e

Merge branch 'main' into mesh_competence_tutorial

744a0ab

Vyp3er marked this pull request as ready for review July 20, 2026 11:33

lenaploetzke self-requested a review July 20, 2026 12:14

lenaploetzke self-assigned this Jul 21, 2026

lenaploetzke requested changes Jul 27, 2026

View reviewed changes

lenaploetzke assigned Vyp3er and unassigned lenaploetzke Jul 27, 2026

Fixed all errors mentioned in Pull Request comments.

761d9df

Vyp3er assigned lenaploetzke Aug 6, 2026

lenaploetzke reviewed Aug 7, 2026

View reviewed changes

lenaploetzke removed their assignment Aug 7, 2026

	* Element data competences are used to store data in the mesh elements and work with it in different ways
	* Element data competences are used to store data in the mesh elements and work with it in different ways.

	* Cache competences are used to store data in the mesh elements to work with it more efficiently, e.g. to avoid recomputing the same data multiple times.
	* Cache competences are used to store data in the mesh elements to avoid recomputing the same data multiple times.


		#include <t8.h> /** General t8code header. Always include this. */

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

	* They are templated on the underlying element type and inherit from
	* They are templated on the underlying element type TUnderlying and inherit from

	using custom_mesh = mesh<custom_element_competences>;
	using custom_mesh_class = mesh<custom_element_competences>;

	/* Creating a custom mesh with the mesh_type including our custom competence pack and the initial refinement level 2. */
	/* Creating a mesh with the mesh_type including our custom competence pack. */

	auto custom = handle_hypercube_hybrid_uniform_default<custom_mesh> (level, comm);
	auto custom_mesh = handle_hypercube_hybrid_uniform_default<custom_mesh> (level, comm);

	t8_global_productionf (" [t8 Step A Mesh handle] Demonstrating the custom competence 'Squared Value'.\n");
	t8_global_productionf (" [t8 Step A Mesh handle] Demonstrating the custom competence 'squared volume'.\n");

Uh oh!

Conversation

Vyp3er commented Jul 20, 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 20, 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!

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

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

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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Vyp3er commented Jul 20, 2026 •

edited

Loading

codecov Bot commented Jul 20, 2026 •

edited

Loading