add interface for replicated partition search

doc/author_brandt.txt

@@ -0,0 +1 @@
+I place my contributions to t8code under the FreeBSD license. Hannes Brandt ([email protected])

src/Makefile.am

@@ -53,7 +53,9 @@ libt8_installed_headers_forest = \
   src/t8_forest/t8_forest_profiling.h \
   src/t8_forest/t8_forest_io.h \
   src/t8_forest/t8_forest_adapt.h \
-  src/t8_forest/t8_forest_iterate.h src/t8_forest/t8_forest_partition.h
+  src/t8_forest/t8_forest_iterate.h \
+  src/t8_forest/t8_forest_partition.h \
+  src/t8_forest/t8_forest_search/t8_forest_search.hxx
 libt8_installed_headers_geometry = \
   src/t8_geometry/t8_geometry.h \
   src/t8_geometry/t8_geometry_handler.hxx \
@@ -139,6 +141,7 @@ libt8_compiled_sources = \
   src/t8_forest/t8_forest_partition.cxx src/t8_forest/t8_forest.cxx \
   src/t8_forest/t8_forest_private.c \
   src/t8_forest/t8_forest_ghost.cxx src/t8_forest/t8_forest_iterate.cxx \
+  src/t8_forest/t8_forest_search/t8_forest_search.cxx \
   src/t8_version.c \
   src/t8_vtk.c src/t8_forest/t8_forest_balance.cxx \
   src/t8_forest/t8_forest_netcdf.cxx \

src/t8_forest/t8_forest_iterate.cxx

@@ -536,4 +536,11 @@ t8_forest_iterate_replace (t8_forest_t forest_new, t8_forest_t forest_old, t8_fo
   t8_global_productionf ("Done t8_forest_iterate_replace\n");
 }
 
+void
+t8_forest_search_partition (const t8_forest_t forest, t8_forest_partition_search_fn search_fn,
+                            t8_forest_partition_query_fn query_fn, sc_array_t *queries)
+{
+  T8_ASSERT (0); /* not implemented yet */
+}
+
 T8_EXTERN_C_END ();

src/t8_forest/t8_forest_iterate.h

@@ -79,6 +79,48 @@ typedef void (*t8_forest_query_fn) (t8_forest_t forest, const t8_locidx_t ltreei
                                     const int is_leaf, const t8_element_array_t *leaf_elements,
                                     const t8_locidx_t tree_leaf_index, sc_array_t *queries, sc_array_t *query_indices,
                                     int *query_matches, const size_t num_active_queries);
+/**
+ * A call-back function used by \ref t8_forest_search_partition describing a search-criterion. Is called on an element
+ * and the search criterion should be checked on that element. Return true if the search criterion is met, false
+ * otherwise.
+ *
+ * \param[in] forest              the forest
+ * \param[in] ltreeid             the local tree id of the current tree in the cmesh. Since the cmesh has to be
+ *                                replicated, it coincides with the global tree id.
+ * \param[in] element             the element for which the search criterion is checked
+ * \param[in] pfirst              the first processor that owns part of \a element. Guaranteed to be non-empty.
+ * \param[in] plast               the last processor that owns part of \a element. Guaranteed to be non-empty.
+ * \returns                       non-zero if the search criterion is met, zero otherwise.
+ */
+typedef int (*t8_forest_partition_search_fn) (const t8_forest_t forest, const t8_locidx_t ltreeid,
+                                              const t8_element_t *element, const int pfirst, const int plast);
+
+/**
+ * A call-back function used by \ref t8_forest_search_partition for queries. Is called on an element and all queries are
+ * checked on that element. All positive queries are passed further down to the children of the element. The results of
+ * the check are stored in \a query_matches.
+ *
+ * \param[in] forest              the forest
+ * \param[in] ltreeid             the local tree id of the current tree in the cmesh. Since the cmesh has to be
+ *                                replicated, it coincides with the global tree id.
+ * \param[in] element             the element for which the query is executed
+ * \param[in] pfirst              the first processor that owns part of \a element. Guaranteed to be non-empty.
+ * \param[in] plast               the last processor that owns part of \a element. Guaranteed to be non-empty.
+ *                                if this is equal to \a pfirst, then the recursion will stop for
+ *                                \a element's branch after this function returns.
+ * \param[in] queries             an array of queries that are checked by the function
+ * \param[in] query_indices       an array of size_t entries, where each entry is an index of a query in \a queries.
+ * \param[in, out] query_matches  an array of length \a num_active_queries.
+ *                                If the element is not a leaf must be set to true or false at the i-th index for
+ *                                each query, specifying whether the element 'matches' the query of the i-th query
+ *                                index or not. When the element is a leaf we can return before all entries are set.
+ * \param[in] num_active_queries  The number of currently active queries (equals the number of entries of
+ *                                \a query_matches and entries of \a query_indices).
+ */
+typedef void (*t8_forest_partition_query_fn) (const t8_forest_t forest, const t8_locidx_t ltreeid,
+                                              const t8_element_t *element, const int pfirst, const int plast,
+                                              void *queries, sc_array_t *query_indices, int *query_matches,
+                                              const size_t num_active_queries);
 
 T8_EXTERN_C_BEGIN ();
 
@@ -134,6 +176,25 @@ t8_forest_search (t8_forest_t forest, t8_forest_search_fn search_fn, t8_forest_q
 void
 t8_forest_iterate_replace (t8_forest_t forest_new, t8_forest_t forest_old, t8_forest_replace_t replace_fn);
 
+/**
+ * Perform a top-down search of the global partition, executing a callback on
+ * each intermediate element. The search will enter each tree at least once.
+ * The recursion will only go down branches that are split between multiple processors.
+ * This is not a collective function. It does not communicate.
+ * The function expects the coarse mesh to be replicated.
+ * If the callback returns false for an element, its descendants
+ * are not further searched.
+ * To pass user data to \b search_fn function use \ref t8_forest_set_user_data
+ *
+ * \param[in] forest              the forest to be searched
+ * \param[in] search_fn           a search callback function called on elements
+ * \param[in] query_fn            a query callback function called for all active queries of an element
+ * \param[in,out] queries         an array of queries that are checked by the function
+ */
+void
+t8_forest_search_partition (const t8_forest_t forest, t8_forest_partition_search_fn search_fn,
+                            t8_forest_partition_query_fn query_fn, sc_array_t *queries);
+
 T8_EXTERN_C_END ();
 
 #endif /* !T8_FOREST_ITERATE_H */