Feature: extend leaf face neighbor to non-balanced forests and ghosts [Review wanted, but still WIP][2/2]

[holke]

Closes #1737

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

Builds upon #1714

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

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)

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.

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

[Davknapp]

A very small first batch of comments. Need to have a more detailed look into it for a propper review. But thanks for the addition ;)

[Davknapp]

Suggested change

	t8_forest_leaf_face_neighbors_iterate (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, int face,
	int is_leaf, [[maybe_unused]] const t8_element_array_t *const leaf_elements,
	t8_locidx_t tree_leaf_index, void *user_data)
	t8_forest_leaf_face_neighbors_iterate (t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *element, const int face,
	const bool is_leaf, [[maybe_unused]] const t8_element_array_t *const leaf_elements,
	const t8_locidx_t tree_leaf_index, void *user_data)

[Davknapp]

I think there is already a function that returns the tree-id of a local or ghost tree. If so, please use it instead.

[Davknapp]

Suggested change

	void
	t8_forest_leaf_face_neighbors_ext (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *leaf_or_ghost,
	t8_element_t **pneighbor_leaves[], int face, int *dual_faces[], int *num_neighbors,
	t8_locidx_t **pelement_indices, t8_eclass_t *pneigh_eclass, t8_gloidx_t *gneigh_tree,
	int *orientation)
	void
	t8_forest_leaf_face_neighbors_ext (t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *leaf_or_ghost,
	t8_element_t **pneighbor_leaves[], const int face, int *dual_faces[], int *num_neighbors,
	t8_locidx_t **pelement_indices, t8_eclass_t *pneigh_eclass, t8_gloidx_t *gneigh_tree,
	int *orientation)