Documentation: README files /src and /src/t8_cmesh #1855

holke · 2025-09-17T09:02:43Z

Describe your changes here:

We add new README.md files for the src/ and src/t8_cmesh folders in t8code to document the folder structure and to make it easier for devs to get into t8code.

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.
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 script/find_all_source_files.scp 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).

src/README.md

codecov · 2025-09-19T11:55:01Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.42%. Comparing base (b9633d6) to head (8a08aa5).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1855   +/-   ##
=======================================
  Coverage   74.42%   74.42%           
=======================================
  Files         101      101           
  Lines       19204    19204           
=======================================
  Hits        14293    14293           
  Misses       4911     4911

☔ View full report in Codecov by Sentry.
📢 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

Thank you for this nice overview :)

lenaploetzke · 2025-09-22T08:55:26Z

src/README.md

+
+### [src](https://github.com/DLR-AMR/t8code/tree/main/src)
+
+The main source folder, it holds main header files like [t8.h](https://github.com/DLR-AMR/t8code/blob/main/src/t8.h), [t8_cmesh.hxx](https://github.com/DLR-AMR/t8code/blob/main/src/t8_cmesh.hxx) and more.


We talked about changing the references to only folder structures (Similar as you did for the cmesh readme in line 14). I think it would be better to use this everywhere instead of this reference to the main branch :)

lenaploetzke · 2025-09-22T09:09:00Z

src/README.md

+
+### [src](https://github.com/DLR-AMR/t8code/tree/main/src)
+
+The main source folder, it holds main header files like [t8.h](https://github.com/DLR-AMR/t8code/blob/main/src/t8.h), [t8_cmesh.hxx](https://github.com/DLR-AMR/t8code/blob/main/src/t8_cmesh.hxx) and more.


Suggested change

The main source folder, it holds main header files like [t8.h](https://github.com/DLR-AMR/t8code/blob/main/src/t8.h), [t8_cmesh.hxx](https://github.com/DLR-AMR/t8code/blob/main/src/t8_cmesh.hxx) and more.

The main source folder. It holds main header files like [t8.h](https://github.com/DLR-AMR/t8code/blob/main/src/t8.h), [t8_cmesh.hxx](https://github.com/DLR-AMR/t8code/blob/main/src/t8_cmesh.hxx) and more.

lenaploetzke · 2025-09-22T09:09:41Z

src/README.md

+#### [src/t8_cmesh](https://github.com/DLR-AMR/t8code/tree/main/src/t8_cmesh)
+
+Contains implementation details of algorithms and data structures related to the coarse mesh.
+See [cmesh README](t8_cmesh/README.md) and the tutorial about coarse meshes: [Creating a coarse mesh](https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh)


Suggested change

See [cmesh README](t8_cmesh/README.md) and the tutorial about coarse meshes: [Creating a coarse mesh](https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh)

See [cmesh README](t8_cmesh/README.md) and the tutorials about coarse meshes: [Creating a coarse mesh](https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh)

lenaploetzke · 2025-09-22T09:11:01Z

src/README.md

+#### [src/t8_data](https://github.com/DLR-AMR/t8code/tree/feature-folder_README/src/t8_data)
+
+Contains data handling classes and algorithms related to data containers, including arrays to handle element data.
+See [data README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_data/README)


Suggested change

See [data README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_data/README)

See [data README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_data/README).

lenaploetzke · 2025-09-22T09:21:34Z

src/README.md

+
+#### [src/t8_types](https://github.com/DLR-AMR/t8code/tree/main/src/t8_types)
+
+Custom data types and strong types. Also contains t8_vec vector implementation.


Suggested change

Custom data types and strong types. Also contains t8_vec vector implementation.

Custom data types and strong types. Also contains `t8_vec` vector implementation.

lenaploetzke · 2025-09-22T09:23:26Z

src/README.md

+#### [src/t8_forest](https://github.com/DLR-AMR/t8code/tree/main/src/t8_forest)
+
+Contains implementation details of algorithms and data structures related to the forest, i.e. the actual computational mesh.
+See [forest README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_forest/README) and the tutorials, [Step 2](https://github.com/DLR-AMR/t8code/wiki/Step-2---Creating-a-uniform-forest), [Step 3](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest), [Step 4](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest).


Suggested change

See [forest README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_forest/README) and the tutorials, [Step 2](https://github.com/DLR-AMR/t8code/wiki/Step-2---Creating-a-uniform-forest), [Step 3](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest), [Step 4](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest).

See [forest README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_forest/README) and the tutorials, [Step 2](https://github.com/DLR-AMR/t8code/wiki/Step-2---Creating-a-uniform-forest), [Step 3](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest), [Step 4](https://github.com/DLR-AMR/t8code/wiki/Step-4---Partition,-Balance,-Ghost).

lenaploetzke · 2025-09-22T09:24:27Z

src/README.md

+#### [src/t8_types](https://github.com/DLR-AMR/t8code/tree/main/src/t8_types)
+
+Custom data types and strong types. Also contains t8_vec vector implementation.
+See [types README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_schemes/README).


Suggested change

See [types README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_schemes/README).

See [types README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_types/README).

lenaploetzke · 2025-09-22T11:11:01Z

src/t8_cmesh/README.md

+See also our Wiki tutorials [Creating a coarse mesh](https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh)
+and [Building a Cmesh by hand](https://github.com/DLR-AMR/t8code/wiki/Building-a-Cmesh-by-hand).
+
+Your entry point should be [t8_cmesh.h](https://github.com/DLR-AMR/t8code/blob/18e8af64286bef9370042a8c4d7885d279d2b933/src/t8_cmesh.h) which is the main cmesh interface.


Suggested change

Your entry point should be [t8_cmesh.h](https://github.com/DLR-AMR/t8code/blob/18e8af64286bef9370042a8c4d7885d279d2b933/src/t8_cmesh.h) which is the main cmesh interface.

Your entry point to familiarize yourself with the code should be [t8_cmesh.h](https://github.com/DLR-AMR/t8code/blob/18e8af64286bef9370042a8c4d7885d279d2b933/src/t8_cmesh.h) which is the main cmesh interface.

lenaploetzke · 2025-09-22T11:12:51Z

src/t8_forest/t8_forest_search/README.md

@@ -0,0 +1 @@
+


Suggested change

TODO

holke added 7 commits September 17, 2025 11:02

Create README.md

9a3d732

Create README in t8_cmesh

9de41de

Create README in t8_data

6d32542

Rename README to README.md

d249499

Started README in src.

c32957b

WIP src README

2e20f0f

Update README.md

4c37160

holke changed the title ~~Create README.md~~ Documentation: README files for the subfolders Sep 17, 2025

holke added 15 commits September 17, 2025 14:33

Rename README to README.md

970a96d

Update README.md

4a1308f

Create README.md for forest

f763e69

Create README.md in forest_search

f8eb131

Create README.md for geometry

2ddaabe

Create README.md for geometry implementations

40df556

Create README.md in scheme

473eedb

Create README.md in default scheme

128b003

Create README.md in standalone scheme

2b907e7

Create README.md in types

456bf77

Create README.md in vector helper

2a3c8da

Create README.md in t8_vtk

08d3a39

Create README.md in t8_with_vtk

12065de

Update README.md

4a3386f

Create README.md in cmesh_vertex_conn

25281a6

holke commented Sep 17, 2025

View reviewed changes

src/README.md Outdated Show resolved Hide resolved

holke added 3 commits September 17, 2025 14:43

Update src/README.md

18e8af6

Update README.md for cmesh

1a130f0

Update README.md cmesh

2a1cc2d

holke changed the title ~~Documentation: README files for the subfolders~~ Documentation: README files /src and /src/t8_cmesh Sep 19, 2025

Merge branch 'main' into feature-folder_README

8a08aa5

holke marked this pull request as ready for review September 19, 2025 11:25

holke added the documentation label Sep 19, 2025

holke mentioned this pull request Sep 19, 2025

Document t8code's folder structure with README.md files. #1872

Open

6 tasks

lenaploetzke self-requested a review September 22, 2025 08:50

lenaploetzke self-assigned this Sep 22, 2025

lenaploetzke reviewed Sep 22, 2025

View reviewed changes

lenaploetzke assigned holke and unassigned lenaploetzke Sep 22, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Documentation: README files /src and /src/t8_cmesh #1855

Documentation: README files /src and /src/t8_cmesh #1855

Uh oh!

holke commented Sep 17, 2025 •

edited

Loading

Uh oh!

Uh oh!

codecov bot commented Sep 19, 2025 •

edited

Loading

Uh oh!

lenaploetzke left a comment

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

lenaploetzke Sep 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		### [src](https://github.com/DLR-AMR/t8code/tree/main/src)

		The main source folder, it holds main header files like [t8.h](https://github.com/DLR-AMR/t8code/blob/main/src/t8.h), [t8_cmesh.hxx](https://github.com/DLR-AMR/t8code/blob/main/src/t8_cmesh.hxx) and more.

	The main source folder, it holds main header files like [t8.h](https://github.com/DLR-AMR/t8code/blob/main/src/t8.h), [t8_cmesh.hxx](https://github.com/DLR-AMR/t8code/blob/main/src/t8_cmesh.hxx) and more.
	The main source folder. It holds main header files like [t8.h](https://github.com/DLR-AMR/t8code/blob/main/src/t8.h), [t8_cmesh.hxx](https://github.com/DLR-AMR/t8code/blob/main/src/t8_cmesh.hxx) and more.

	See [cmesh README](t8_cmesh/README.md) and the tutorial about coarse meshes: [Creating a coarse mesh](https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh)
	See [cmesh README](t8_cmesh/README.md) and the tutorials about coarse meshes: [Creating a coarse mesh](https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh)

	See [data README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_data/README)
	See [data README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_data/README).


		#### [src/t8_types](https://github.com/DLR-AMR/t8code/tree/main/src/t8_types)

		Custom data types and strong types. Also contains t8_vec vector implementation.

	See [forest README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_forest/README) and the tutorials, [Step 2](https://github.com/DLR-AMR/t8code/wiki/Step-2---Creating-a-uniform-forest), [Step 3](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest), [Step 4](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest).
	See [forest README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_forest/README) and the tutorials, [Step 2](https://github.com/DLR-AMR/t8code/wiki/Step-2---Creating-a-uniform-forest), [Step 3](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest), [Step 4](https://github.com/DLR-AMR/t8code/wiki/Step-4---Partition,-Balance,-Ghost).

	See [types README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_schemes/README).
	See [types README](https://github.com/DLR-AMR/t8code/tree/main/src/t8_types/README).

	Your entry point should be [t8_cmesh.h](https://github.com/DLR-AMR/t8code/blob/18e8af64286bef9370042a8c4d7885d279d2b933/src/t8_cmesh.h) which is the main cmesh interface.
	Your entry point to familiarize yourself with the code should be [t8_cmesh.h](https://github.com/DLR-AMR/t8code/blob/18e8af64286bef9370042a8c4d7885d279d2b933/src/t8_cmesh.h) which is the main cmesh interface.

Documentation: README files /src and /src/t8_cmesh #1855

Are you sure you want to change the base?

Documentation: README files /src and /src/t8_cmesh #1855

Uh oh!

Conversation

holke commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

General

Tests

Scripts and Wiki

License

Uh oh!

Uh oh!

codecov bot commented Sep 19, 2025 • 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!

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!

3 participants

holke commented Sep 17, 2025 •

edited

Loading

codecov bot commented Sep 19, 2025 •

edited

Loading