t8_forest_iterate.h

Go to the documentation of this file.

/*
  This file is part of t8code.
  t8code is a C library to manage a collection (a forest) of multiple
  connected adaptive space-trees of general element classes in parallel.
 
  Copyright (C) 2015 the developers
 
  t8code is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.
 
  t8code is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with t8code; if not, write to the Free Software Foundation, Inc.,
  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
 
/* TODO: begin documenting this file: make doxygen 2>&1 | grep t8_forest_iterate */
 
#ifndef T8_FOREST_ITERATE_H
#define T8_FOREST_ITERATE_H
 
#include <t8.h>
#include <t8_forest/t8_forest_general.h>
 
typedef int (*t8_forest_iterate_face_fn) (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element,
                                          int face, void *user_data, t8_locidx_t tree_leaf_index);
 
/*
 * forest          the forest
 * ltreeid         the local tree id of the current tree
 * element         the element for which the query is executed
 * is_leaf         true if and only if \a element is a leaf element
 * leaf_elements   the leaf elements in \a forest that are descendants of \a element
 *                 (or the element itself if \a is_leaf is true)
 * tree_leaf_index the local index of the first leaf in \a leaf_elements
 * query           if not NULL, a query that is passed through from the search function
 * query_index     if \a query is not NULL the index of \a query in the queries array from
 *                 \ref t8_forest_search
 *
 * return          if \a query is not NULL: true if and only if the element 'matches' the query
 *                 if \a query is NULL: true if and only if the search should continue with the
 *                 children of \a element and the queries should be performed for this element.
 */
typedef int (*t8_forest_search_query_fn) (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element,
                                          const int is_leaf, t8_element_array_t *leaf_elements,
                                          t8_locidx_t tree_leaf_index, void *query, size_t query_index);
 
T8_EXTERN_C_BEGIN ();
 
/* TODO: Document */
void
t8_forest_split_array (const t8_element_t *element, t8_element_array_t *leaf_elements, size_t *offsets);
 
/* TODO: comment */
/* Iterate over all leafs of an element that touch a given face of the element */
/* Callback is called in each recursive step with element as input.
 * leaf_index is only not negative if element is a leaf, in which case it indicates
 * the index of the leaf in the leafs of the tree. If it is negative, it is
 * - (index + 1) */
/* Top-down iteration and callback is called on each intermediate level.
 * If it returns false, the current element is not traversed further */
void
t8_forest_iterate_faces (t8_forest_t forest, t8_locidx_t ltreeid, const t8_element_t *element, int face,
                         t8_element_array_t *leaf_elements, void *user_data, t8_locidx_t tree_lindex_of_first_leaf,
                         t8_forest_iterate_face_fn callback);
 
/* Perform a top-down search of the forest, executing a callback on each
 * intermediate element. The search will enter each tree at least once.
 * If the callback returns false for an element, its descendants
 * are not further searched.
 * To pass user data to the search_fn function use \ref t8_forest_set_user_data
 */
void
t8_forest_search (t8_forest_t forest, t8_forest_search_query_fn search_fn, t8_forest_search_query_fn query_fn,
                  sc_array_t *queries);
 
void
t8_forest_iterate_replace (t8_forest_t forest_new, t8_forest_t forest_old, t8_forest_replace_t replace_fn);
 
T8_EXTERN_C_END ();
 
#endif /* !T8_FOREST_ITERATE_H! */