Improvement: own header and source file for forest face neighbor functions

README.md

@@ -75,7 +75,7 @@ We provide a short guide to install t8code in our Wiki [Installation guide](http
 ### Documentation
 
 t8code uses [Doxygen](https://doxygen.nl/) to generate the code documentation. 
-You can find the documentation of our releases on the [t8code website](https://dlr-amr.github.io/t8code/pages/documentation.html).
+You can find the documentation on [readthedocs](https://t8code.readthedocs.io/en/latest/).
 Follow the steps described in our Wiki [Documentation](https://github.com/DLR-AMR/t8code/wiki/Documentation) to create the documentation locally.
 
 

example/advect/t8_advection.cxx

@@ -23,10 +23,7 @@
 #include <sc_options.h>
 #include <sc_statistics.h>
 #include <t8_schemes/t8_default/t8_default.hxx>
-#include <t8_forest/t8_forest_general.h>
-#include <t8_forest/t8_forest_io.h>
-#include <t8_forest/t8_forest_geometrical.h>
-#include <t8_forest/t8_forest_profiling.h>
+#include <t8_forest/t8_forest.h>
 #include <t8_forest/t8_forest_iterate.h>
 #include <t8_forest/t8_forest_partition.h>
 #include <t8_forest/t8_forest_ghost.h>

src/CMakeLists.txt

@@ -108,12 +108,12 @@ if( T8CODE_ENABLE_OCC )
     target_link_libraries( T8 PUBLIC ${OpenCASCADE_LIBRARIES} )
     target_sources(T8 PRIVATE 
       t8_geometry/t8_geometry_implementations/t8_geometry_cad.cxx
-      t8_data/t8_cad.cxx
+      t8_cad/t8_cad.cxx
     )
     install( FILES 
       t8_geometry/t8_geometry_implementations/t8_geometry_cad.hxx
       t8_geometry/t8_geometry_implementations/t8_geometry_cad.h
-      t8_data/t8_cad.hxx
+      t8_cad/t8_cad.hxx
       DESTINATION include
     )
 endif()
@@ -177,7 +177,9 @@ target_sources( T8 PRIVATE
     t8_forest/t8_forest_ghost.cxx 
     t8_forest/t8_forest_iterate.cxx 
     t8_forest/t8_forest_balance.cxx 
-    t8_forest/t8_forest_search/t8_forest_search.cxx 
+    t8_forest/t8_forest_search/t8_forest_search.cxx
+    t8_forest/t8_forest_neighbor/t8_forest_element_face_neighbor.cxx
+    t8_forest/t8_forest_neighbor/t8_forest_leaf_face_neighbor.cxx
     t8_geometry/t8_geometry.cxx 
     t8_geometry/t8_geometry_helpers.c 
     t8_geometry/t8_geometry_base.cxx 

src/t8_data/t8_cad.cxx → src/t8_cad/t8_cad.cxx

@@ -21,7 +21,7 @@
 */
 
 #include <t8.h>
-#include <t8_data/t8_cad.hxx>
+#include <t8_cad/t8_cad.hxx>
 #include <t8_geometry/t8_geometry_implementations/t8_geometry_cad.hxx>
 #include <TopoDS.hxx>
 #include <BRep_Builder.hxx>

src/t8_forest/t8_forest.h

@@ -31,5 +31,7 @@
 #include <t8_forest/t8_forest_geometrical.h>
 #include <t8_forest/t8_forest_profiling.h>
 #include <t8_forest/t8_forest_io.h>
+#include <t8_forest/t8_forest_neighbor/t8_forest_element_face_neighbor.h>
+#include <t8_forest/t8_forest_neighbor/t8_forest_leaf_face_neighbor.h>
 
 #endif /* !T8_FOREST_H */

src/t8_forest/t8_forest_balance.cxx

@@ -27,6 +27,7 @@
 #include <t8_forest/t8_forest_ghost.h>
 #include <t8_forest/t8_forest_general.h>
 #include <t8_forest/t8_forest_profiling.h>
+#include <t8_forest/t8_forest_neighbor/t8_forest_element_face_neighbor.h>
 #include <t8_schemes/t8_scheme.hxx>
 
 /* We want to export the whole implementation to be callable from "C" */

src/t8_forest/t8_forest_general.h

@@ -550,112 +550,6 @@ int
 t8_forest_element_is_leaf_or_ghost (const t8_forest_t forest, const t8_element_t *element, const t8_locidx_t local_tree,
                                     const int check_ghost);
 
-/** Compute the leaf face orientation at given face in a forest.
- * \param [in]    forest  The forest. Must have a valid ghost layer.
- * \param [in]    ltreeid A local tree id.
- * \param [in]    scheme      The eclass scheme of the element.
- * \param [in]    leaf    A leaf in tree \a ltreeid of \a forest.
- * \param [in]    face    The index of the face across which the face neighbors
- *                        are searched.
- * \return                Face orientation encoded as integer.
- *
- * For more information about the encoding of face orientation refer to \ref t8_cmesh_get_face_neighbor.
- */
-int
-t8_forest_leaf_face_orientation (t8_forest_t forest, const t8_locidx_t ltreeid, const t8_scheme_c *scheme,
-                                 const t8_element_t *leaf, const int face);
-
-/** Compute the leaf face neighbors of a forest leaf element or ghost leaf.
- * \param [in]    forest  The forest.
- * \param [in]    ltreeid A local tree id (could also be a ghost tree). 0 <= \a ltreeid < num_local trees+num_ghost_trees
- * \param [in]    leaf    A leaf in tree \a ltreeid of \a forest.
- * \param [out]   pneighbor_leaves Unallocated on input. On output the neighbor
- *                        leaves are stored here.
- * \param [in]    face    The index of the face across which the face neighbors
- *                        are searched.
- * \param [out]   dual_faces On output the face id's of the neighboring elements' faces.
- * \param [out]   num_neighbors On output the number of neighbor leaves.
- * \param [out]   pelement_indices Unallocated on input. On output the element indices
- *                        of the neighbor leaves are stored here.
- *                        0, 1, ... num_local_el - 1 for local leaves and
- *                        num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
- * \param [out]   pneigh_eclass On output the eclass of the neighbor elements.
- * \note If there are no face neighbors, then *pneighbor_leaves = NULL, num_neighbors = 0,
- * and *pelement_indices = NULL on output.
- * \note \a forest must be committed before calling this function.
- * \note If \a forest does not have a ghost layer then leaf elements at the process boundaries have 0 neighbors. (The function output for leaf elements then depends on the parallel partition.)
- * \note Important! This routine allocates memory which must be freed. Do it like this:
- *
- *   if (num_neighbors > 0) {
- *     T8_FREE (pneighbor_leaves);
- *     T8_FREE (pelement_indices);
- *     T8_FREE (dual_faces);
- *   }
- *
- */
-void
-t8_forest_leaf_face_neighbors (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *leaf,
-                               const t8_element_t **pneighbor_leaves[], const int face, int *dual_faces[],
-                               int *num_neighbors, t8_locidx_t **pelement_indices, t8_eclass_t *pneigh_eclass);
-
-/** Like \ref t8_forest_leaf_face_neighbors but also provides information about the global neighbors and the orientation. 
- * \param [in]    forest  The forest. Must have a valid ghost layer.
- * \param [in]    ltreeid A local tree id (could also be a ghost tree). 0 <= \a ltreeid < num_local trees+num_ghost_trees
- * \param [in]    leaf    A leaf in tree \a ltreeid of \a forest.
- * \param [out]   pneighbor_leaves Unallocated on input. On output the neighbor
- *                        leaves are stored here.
- * \param [in]    face    The index of the face across which the face neighbors
- *                        are searched.
- * \param [out]   dual_faces On output the face id's of the neighboring elements' faces.
- * \param [out]   num_neighbors On output the number of neighbor leaves.
- * \param [out]   pelement_indices Unallocated on input. On output the element indices
- *                        of the neighbor leaves are stored here.
- *                        0, 1, ... num_local_el - 1 for local leaves and
- *                        num_local_el , ... , num_local_el + num_ghosts - 1 for ghosts.
- * \param [out]   pneigh_eclass On output the eclass of the neighbor elements.
- * \param [out]   gneigh_tree  The global tree IDs of the neighbor trees.
- * \param [out]   orientation  If not NULL on input, the face orientation is computed and stored here. 
- *                                         Thus, if the face connection is an inter-tree connection the orientation of the tree-to-tree connection is stored. 
- *                                         Otherwise, the value 0 is stored.
- * All other parameters and behavior are identical to \ref t8_forest_leaf_face_neighbors.
- * \note If there are no face neighbors, then *pneighbor_leaves = NULL, num_neighbors = 0,
- * and *pelement_indices = NULL on output.
- * \note \a forest must be committed before calling this function.
- *
- * \note Important! This routine allocates memory which must be freed. Do it like this:
- *
- *   if (num_neighbors > 0) {
- *     T8_FREE (pneighbor_leaves);
- *     T8_FREE (pelement_indices);
- *     T8_FREE (dual_faces);
- *   }
- *
- */
-void
-t8_forest_leaf_face_neighbors_ext (const t8_forest_t forest, const t8_locidx_t ltreeid,
-                                   const t8_element_t *leaf_or_ghost, const 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);
-
-/** Given a leaf element or ghost index in "all local elements + ghosts" enumeration
- * compute the index of the face neighbor of the element - provided that only one or no
- * face neighbors exists.
- * HANDLE WITH CARE. DO NOT CALL IF THE FOREST IS ADAPTED.
- * 
- * \param[in] forest        The forest. Must be committed.
- * \param[in] element_index Index of an element in \a forest. Must have only one or no facen neighbors across the given face.
- *                          0 <= \a element_index < num_local_elements + num_ghosts
- * \param[in] face_index    Index of a face of \a element.
- * \param[in] global_treeid Global index of the tree that contains \a element.
- * \param[out] dual_face    Return value, the dual_face index of the face neighbor.
- * \return The index of the face neighbor leaf (local element or ghost).
- * \note Do not call if you are unsure about the number of face neighbors. In particular if the forest is adapted and not uniform.
- */
-t8_locidx_t
-t8_forest_same_level_leaf_face_neighbor_index (const t8_forest_t forest, const t8_locidx_t element_index,
-                                               const int face_index, const t8_gloidx_t global_treeid, int *dual_face);
-
 /** Exchange ghost information of user defined element data.
  * \param [in] forest       The forest. Must be committed.
  * \param [in] element_data An array of length num_local_elements + num_ghosts
@@ -844,42 +738,6 @@ t8_forest_get_first_local_leaf_element_id (t8_forest_t forest);
 const t8_scheme_c *
 t8_forest_get_scheme (const t8_forest_t forest);
 
-/** Return the eclass of the tree in which a face neighbor of a given element or ghost
- * lies.
- * \param [in]      forest      A committed forest.
- * \param [in]      ltreeid     The local tree or ghost tree in which the element lies. 0 <= \a ltreeid < num_local_trees + num_ghost_trees
- * \param [in]      elem        An element or ghost in the tree \a ltreeid.
- * \param [in]      face        A face number of \a elem.
- * \return                      The eclass of the local tree or ghost tree that
- *                              is face neighbor of \a elem across \a face.
- *                              T8_ECLASS_INVALID if no neighbor exists.
- */
-t8_eclass_t
-t8_forest_element_neighbor_eclass (const t8_forest_t forest, const t8_locidx_t ltreeid, const t8_element_t *elem,
-                                   const int face);
-
-/** Construct the face neighbor of an element, possibly across tree boundaries.
- * Returns the global tree-id of the tree in which the neighbor element lies in.
- *
- * \param [in] forest       The forest.
- * \param [in] ltreeid      The local tree in which the element lies.
- * \param [in] elem         The element to be considered.
- * \param [in,out] neigh    On input an allocated element of the scheme of the
- *                          face_neighbors eclass.
- *                          On output, this element's data is filled with the
- *                          data of the face neighbor. If the neighbor does not exist
- *                          the data could be modified arbitrarily.
- * \param [in] neigh_eclass The eclass of \a neigh.
- * \param [in] face         The number of the face along which the neighbor should be constructed.
- * \param [out] neigh_face  The number of the face viewed from perspective of \a neigh.
- * \return The global tree-id of the tree in which \a neigh is in.
- *        -1 if there exists no neighbor across that face. Domain boundary.
- *        -2 if the neighbor is not in a local tree or ghost tree. Process/Ghost boundary.
- */
-t8_gloidx_t
-t8_forest_element_face_neighbor (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *elem, t8_element_t *neigh,
-                                 const t8_eclass_t neigh_eclass, int face, int *neigh_face);
-
 /**
  * TODO: Can be removed since it is unused.
  * 

src/t8_forest/t8_forest_ghost.cxx

@@ -26,6 +26,7 @@
 #include <t8_forest/t8_forest_private.h>
 #include <t8_forest/t8_forest_iterate.h>
 #include <t8_forest/t8_forest_general.h>
+#include <t8_forest/t8_forest_neighbor/t8_forest_element_face_neighbor.h>
 #include <t8_schemes/t8_scheme.hxx>
 #include <t8_cmesh/t8_cmesh_trees.h>
 #include <t8_data/t8_containers.h>