Feature: extend leaf face neighbor to non-balanced forests and ghosts [N/N]

[holke]

Closes #1737 and closes #1299

Disclaimer

This PR is not 2k lines as it shows currently.
It is based on many changes that are parts of different PRs but until these are not merged, their lines will show up in the count here.
I listed all the PRs below and also marked the sections that do not need review in the "Files Changed" tab.

Describe your changes here:

This has gotten quite large and will be split up and take some time.
I am putting this up here now to start the review early.

I would like to have a review on this because the algorithm is now working.
The review can focus mostly on the leaf_face_neighbor functionality.
It is still in draft status, because

a) there is still low-level functionality missing to make this work on all element shapes
b) i will split this up into multiple PRs eventually
c) not all tests pass, due to missing low-level functionality

Here is an overview over the exsiting PRs that cover changes from this one.
So a review of this PR can exclude all the listed once below:

Merge #1301 first (t8_element_array_find, t8_forest_element_is_leaf_or_ghost, t8_forest_tree_is_ghost, t8_forest_element_is_ghost)

• Merge Feature: Ancestor search #1714 first (element_is_ancestor and ancestor search)
• Merge Feature: Compute the eclass of a tree or ghost neighbor in the cmesh #1806 first (t8_cmesh_get_tree_face_neighbor_eclass )
• Merge Bugfix: Fix issue 1951 half face neighbor order #1952 first
• Merge Bugfix: VTK Output of empty partitions #1954 first (Bugfix in VTK empty partitions)
• Merge Feature: Add eclass string for invalid eclass #1955 first (eclass invalid string)
• Merge Feature: ancestor face computation function for the scheme #1958 first (element_face_get_ancestor_face)
• Merge feature: const all params in face iterator #1968 first (const params for face iterator)

Description

This PR extends the leaf face neighbor computation in two ways simultaneously:
a) extend it to ghosts, thus we can compute neighbors of ghosts and neighbors that are ghosts
b) extend it to non-balanced forests. So far a 2:1 condition was required, this is no longer the case.

The main contributions are

• extending many "low-level" element and element array handling functions to ghosts (Could be own PR)
• extending the face iteration function to ghosts
• t8_element_array_find function to search for an element in an array (Should be its own PR)
• t8_forest_leaf_face_neighbors_ext extension to non-balances and ghosts
• t8_forest_same_level_leaf_face_neighbor_index to compute the data indices of neighbors if only single neighbor (TODO: this was
  implemented while the lfn function did not work for adaptive forests, need to check whether to extend this function to all forests now) (Should be its own PR)
• a test for the t8_forest_leaf_face_neighbors_ext and t8_forest_same_level_leaf_face_neighbor_index
• Common header for unit test adapt callbacks that we can reuse
• A new functionality to compute the "Ancestor face" - given a face of an element and a coarser level where the face is a subface of, compute the face number at the coarser level

Edit: The function was so far only tested for quads and hexes due to the missing face ancesor #1738. A first test with lines does fail - i need to investigate what is going on. (t8_gtest_face_neighbors/forest_face_neighbors.test_face_neighbors/t8_cmesh_new_from_class_Line_sc_MPI_COMM_WORLD_default)
Edit2: It now works for all element shapes :)

What is still open to get this out of draft:

• Split into multiple PRs
• Implement a scheme function that computes a face index of an ancestor. I.e. Given an element E, a face f of E and and ancestor A (or a level) of E that shares the face, return the face index f_A of the ancestor face of f.
  (see Feature: ancestor face computation function for the scheme #1958)

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

[holke]

Added an extra file to reuse adaptation callbacks in tests.
This could be an extra PR as well, if you think so.

[holke]

Adressed in #1972

[holke]

See #1958

[holke]

See #1714

[holke]

See #1714

[holke]

I am taking this out of draft and into review now :)

I split this up in multiple PRs that should be merged before this one.
See the list in the description above.
Also, i marked in the diff-view every file/function that belongs to a different PR and does not need to be reviewed here.

I will still implement one feature, namely being able to compute face neighbors if no ghost was created.

[holke]

It is now possible to compute the face neighbor if the forest has no ghost (then no neighbor are found for process boundary elements).
Extended the function and added a test case.

[codecov]

Codecov Report

❌ Patch coverage is 91.87359% with 36 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.69%. Comparing base (1124119) to head (360e65f).
⚠️ Report is 15 commits behind head on main.

Files with missing lines	Patch %	Lines
src/t8_forest/t8_forest_ghost.cxx	25.80%	23 Missing ⚠️
src/t8_forest/t8_forest.cxx	96.65%	8 Missing ⚠️
src/t8_forest/t8_forest_private.cxx	94.44%	2 Missing ⚠️
src/t8_schemes/t8_scheme_helpers.hxx	89.47%	2 Missing ⚠️
src/t8_data/t8_containers.cxx	92.30%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1736      +/-   ##
==========================================
+ Coverage   75.66%   76.69%   +1.02%     
==========================================
  Files         105      105              
  Lines       18646    18852     +206     
==========================================
+ Hits        14109    14459     +350     
+ Misses       4537     4393     -144     

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