t8_forest.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 */
 
#ifndef T8_FOREST_H
#define T8_FOREST_H
 
#include <sc_statistics.h>
#include <t8_cmesh.h>
#include <t8_element.h>
#include <t8_vtk.h>
#include <t8_data/t8_containers.h>
 
typedef struct t8_forest *t8_forest_t;
typedef struct t8_tree *t8_tree_t;
 
typedef enum
{
  T8_GHOST_NONE = 0,  
  T8_GHOST_FACES,     
  T8_GHOST_EDGES,     
  T8_GHOST_VERTICES   
} t8_ghost_type_t;
 
typedef void        (*t8_generic_function_pointer) (void);
 
T8_EXTERN_C_BEGIN ();
 
typedef void        (*t8_forest_replace_t) (t8_forest_t forest_old,
                                            t8_forest_t forest_new,
                                            t8_locidx_t which_tree,
                                            t8_eclass_scheme_c *ts,
                                            int refine,
                                            int num_outgoing,
                                            t8_locidx_t first_outgoing,
                                            int num_incoming,
                                            t8_locidx_t first_incoming);
 
/* TODO: Do we really need the forest argument? Since the forest is not committed yet it
 *       seems dangerous to expose to the user. */
typedef int         (*t8_forest_adapt_t) (t8_forest_t forest,
                                          t8_forest_t forest_from,
                                          t8_locidx_t which_tree,
                                          t8_locidx_t lelement_id,
                                          t8_eclass_scheme_c *ts,
                                          const int is_family,
                                          const int num_elements,
                                          t8_element_t *elements[]);
 
void                t8_forest_init (t8_forest_t *pforest);
 
int                 t8_forest_is_initialized (t8_forest_t forest);
 
int                 t8_forest_is_committed (t8_forest_t forest);
 
int                 t8_forest_is_equal (t8_forest_t forest_a,
                                        t8_forest_t forest_b);
 
void                t8_forest_set_cmesh (t8_forest_t forest,
                                         t8_cmesh_t cmesh, sc_MPI_Comm comm);
 
void                t8_forest_set_scheme (t8_forest_t forest,
                                          t8_scheme_cxx_t *scheme);
 
void                t8_forest_set_level (t8_forest_t forest, int level);
 
void                t8_forest_set_copy (t8_forest_t forest,
                                        const t8_forest_t from);
 
/* TODO: make recursive flag to int specifying the number of recursions? */
void                t8_forest_set_adapt (t8_forest_t forest,
                                         const t8_forest_t set_from,
                                         t8_forest_adapt_t adapt_fn,
                                         int recursive);
 
void                t8_forest_set_user_data (t8_forest_t forest, void *data);
 
void               *t8_forest_get_user_data (t8_forest_t forest);
 
void                t8_forest_set_user_function (t8_forest_t forest,
                                                 t8_generic_function_pointer
                                                 functrion);
 
t8_generic_function_pointer t8_forest_get_user_function (t8_forest_t forest);
 
void                t8_forest_set_partition (t8_forest_t forest,
                                             const t8_forest_t set_from,
                                             int set_for_coarsening);
 
void                t8_forest_set_balance (t8_forest_t forest,
                                           const t8_forest_t set_from,
                                           int no_repartition);
 
void                t8_forest_set_ghost (t8_forest_t forest, int do_ghost,
                                         t8_ghost_type_t ghost_type);
 
void                t8_forest_set_ghost_ext (t8_forest_t forest, int do_ghost,
                                             t8_ghost_type_t ghost_type,
                                             int ghost_version);
 
/* TODO: use assertions and document that the forest_set (..., from) and
 *       set_load are mutually exclusive. */
void                t8_forest_set_load (t8_forest_t forest,
                                        const char *filename);
 
void                t8_forest_comm_global_num_elements (t8_forest_t forest);
 
void                t8_forest_commit (t8_forest_t forest);
 
int                 t8_forest_get_maxlevel (t8_forest_t forest);
 
t8_locidx_t         t8_forest_get_local_num_elements (t8_forest_t forest);
 
t8_gloidx_t         t8_forest_get_global_num_elements (t8_forest_t forest);
 
t8_locidx_t         t8_forest_get_num_ghosts (t8_forest_t forest);
 
t8_eclass_t         t8_forest_get_eclass (t8_forest_t forest,
                                          t8_locidx_t ltreeid);
 
t8_locidx_t         t8_forest_get_local_id (t8_forest_t forest,
                                            t8_gloidx_t gtreeid);
 
t8_locidx_t         t8_forest_ltreeid_to_cmesh_ltreeid (t8_forest_t forest,
                                                        t8_locidx_t ltreeid);
 
t8_locidx_t         t8_forest_cmesh_ltreeid_to_ltreeid (t8_forest_t forest,
                                                        t8_locidx_t lctreeid);
 
t8_ctree_t          t8_forest_get_coarse_tree (t8_forest_t forest,
                                               t8_locidx_t ltreeid);
 
void                t8_forest_leaf_face_neighbors (t8_forest_t forest,
                                                   t8_locidx_t ltreeid,
                                                   const t8_element_t *leaf,
                                                   t8_element_t
                                                   **pneighbor_leafs[],
                                                   int face,
                                                   int *dual_faces[],
                                                   int *num_neighbors,
                                                   t8_locidx_t
                                                   **pelement_indices,
                                                   t8_eclass_scheme_c
                                                   **pneigh_scheme,
                                                   int forest_is_balanced);
 
/* TODO: In \ref t8_forest_ghost_cxx we already implemented a begin and end function
 *       that allow for overlapping communication and computation. We will make them
 *       available in this interface in the future. */
void                t8_forest_ghost_exchange_data (t8_forest_t forest,
                                                   sc_array_t *element_data);
 
void                t8_forest_set_profiling (t8_forest_t forest,
                                             int set_profiling);
 
/* TODO: document */
void                t8_forest_compute_profile (t8_forest_t forest);
 
const sc_statinfo_t *t8_forest_profile_get_adapt_stats (t8_forest_t forest);
 
const sc_statinfo_t *t8_forest_profile_get_ghost_stats (t8_forest_t forest);
 
const sc_statinfo_t *t8_forest_profile_get_partition_stats (t8_forest_t
                                                            forest);
 
const sc_statinfo_t *t8_forest_profile_get_commit_stats (t8_forest_t forest);
 
const sc_statinfo_t *t8_forest_profile_get_balance_stats (t8_forest_t forest);
 
const sc_statinfo_t *t8_forest_profile_get_balance_rounds_stats (t8_forest_t
                                                                 forest);
 
void                t8_forest_print_profile (t8_forest_t forest);
 
double              t8_forest_profile_get_adapt_time (t8_forest_t forest);
 
double              t8_forest_profile_get_partition_time (t8_forest_t forest,
                                                          int *procs_sent);
 
double              t8_forest_profile_get_balance_time (t8_forest_t forest,
                                                        int *balance_rounds);
 
double              t8_forest_profile_get_ghost_time (t8_forest_t forest,
                                                      t8_locidx_t
                                                      *ghosts_sent);
 
double              t8_forest_profile_get_ghostexchange_waittime (t8_forest_t
                                                                  forest);
 
void                t8_forest_ghost_print (t8_forest_t forest);
 
void                t8_forest_partition_cmesh (t8_forest_t forest,
                                               sc_MPI_Comm comm,
                                               int set_profiling);
 
sc_MPI_Comm         t8_forest_get_mpicomm (t8_forest_t forest);
 
t8_gloidx_t         t8_forest_get_first_local_tree_id (t8_forest_t forest);
 
t8_locidx_t         t8_forest_get_num_local_trees (t8_forest_t forest);
 
t8_locidx_t         t8_forest_get_num_ghost_trees (t8_forest_t forest);
 
t8_gloidx_t         t8_forest_get_num_global_trees (t8_forest_t forest);
 
t8_gloidx_t         t8_forest_global_tree_id (t8_forest_t forest,
                                              t8_locidx_t ltreeid);
 
t8_tree_t           t8_forest_get_tree (t8_forest_t forest,
                                        t8_locidx_t ltree_id);
 
double             *t8_forest_get_tree_vertices (t8_forest_t forest,
                                                 t8_locidx_t ltreeid);
 
t8_element_array_t *t8_forest_tree_get_leafs (t8_forest_t forest,
                                              t8_locidx_t ltree_id);
 
t8_cmesh_t          t8_forest_get_cmesh (t8_forest_t forest);
 
t8_element_t       *t8_forest_get_element (t8_forest_t forest,
                                           t8_locidx_t lelement_id,
                                           t8_locidx_t *ltreeid);
 
t8_element_t       *t8_forest_get_element_in_tree (t8_forest_t forest,
                                                   t8_locidx_t ltreeid,
                                                   t8_locidx_t leid_in_tree);
 
t8_locidx_t         t8_forest_get_tree_num_elements (t8_forest_t forest,
                                                     t8_locidx_t ltreeid);
 
t8_locidx_t         t8_forest_get_tree_element_offset (t8_forest_t forest,
                                                       t8_locidx_t ltreeid);
 
t8_locidx_t         t8_forest_get_tree_element_count (t8_tree_t tree);
 
t8_eclass_t         t8_forest_get_tree_class (t8_forest_t forest,
                                              t8_locidx_t ltreeid);
 
t8_gloidx_t         t8_forest_get_first_local_element_id (t8_forest_t forest);
 
t8_scheme_cxx_t    *t8_forest_get_scheme (t8_forest_t forest);
 
t8_eclass_scheme_c *t8_forest_get_eclass_scheme (t8_forest_t forest,
                                                 t8_eclass_t eclass);
 
t8_eclass_t         t8_forest_element_neighbor_eclass (t8_forest_t forest,
                                                       t8_locidx_t ltreeid,
                                                       const t8_element_t
                                                       *elem, int face);
 
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,
                                                     t8_eclass_scheme_c
                                                     *neigh_scheme, int face,
                                                     int *neigh_face);
 
/* TODO: implement */
void                t8_forest_save (t8_forest_t forest);
 
int                 t8_forest_write_vtk_ext (t8_forest_t forest,
                                             const char *fileprefix,
                                             int write_treeid,
                                             int write_mpirank,
                                             int write_level,
                                             int write_element_id,
                                             int write_ghosts,
                                             int write_curved,
                                             int do_not_use_API,
                                             int num_data,
                                             t8_vtk_data_field_t *data);
 
int                 t8_forest_write_vtk (t8_forest_t forest,
                                         const char *fileprefix);
 
/* TODO: implement */
void                t8_forest_iterate (t8_forest_t forest);
 
void                t8_forest_element_coordinate (t8_forest_t forest,
                                                  t8_locidx_t ltree_id,
                                                  const t8_element_t *element,
                                                  int corner_number,
                                                  double *coordinates);
 
void                t8_forest_element_centroid (t8_forest_t forest,
                                                t8_locidx_t ltreeid,
                                                const t8_element_t *element,
                                                double *coordinates);
 
double              t8_forest_element_diam (t8_forest_t forest,
                                            t8_locidx_t ltreeid,
                                            const t8_element_t *element);
 
double              t8_forest_element_volume (t8_forest_t forest,
                                              t8_locidx_t ltreeid,
                                              const t8_element_t *element);
 
double              t8_forest_element_face_area (t8_forest_t forest,
                                                 t8_locidx_t ltreeid,
                                                 const t8_element_t *element,
                                                 int face);
 
void                t8_forest_element_face_centroid (t8_forest_t forest,
                                                     t8_locidx_t ltreeid,
                                                     const t8_element_t
                                                     *element, int face,
                                                     double centroid[3]);
 
void                t8_forest_element_face_normal (t8_forest_t forest,
                                                   t8_locidx_t ltreeid,
                                                   const t8_element_t
                                                   *element, int face,
                                                   double normal[3]);
 
int                 t8_forest_element_point_inside (t8_forest_t forest,
                                                    t8_locidx_t ltreeid,
                                                    const t8_element_t
                                                    *element,
                                                    const double point[3],
                                                    const double tolerance);
 
/* TODO: if set level and partition/adapt/balance all give NULL, then
 * refine uniformly and partition/adapt/balance the unfiform forest. */
t8_forest_t         t8_forest_new_uniform (t8_cmesh_t cmesh,
                                           t8_scheme_cxx_t *scheme,
                                           int level, int do_face_ghost,
                                           sc_MPI_Comm comm);
 
/* TODO: make user_data const. */
t8_forest_t         t8_forest_new_adapt (t8_forest_t forest_from,
                                         t8_forest_adapt_t adapt_fn,
                                         int recursive, int do_face_ghost,
                                         void *user_data);
 
void                t8_forest_ref (t8_forest_t forest);
 
void                t8_forest_unref (t8_forest_t *pforest);
 
T8_EXTERN_C_END ();
 
#endif /* !T8_FOREST_H */