t8_cmesh_trees.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.
*/
 
#ifndef T8_CMESH_PART_TREE_H
#define T8_CMESH_PART_TREE_H
 
#include <t8.h>
#include <t8_cmesh.h>
#include "t8_cmesh_types.h"
 
T8_EXTERN_C_BEGIN ();
 
/* Interface for the data layout of the coarse trees.
 *
 * The layout is the same for replicated and partitioned meshes.
 * Each process stores a meta array of data arrays. In the replicated case this meta
 * array has only one entry wheras in the partitioned case there is one data array for
 * each processor from which local trees were received in the last partition step
 * (and only one meta array if the cmesh arised from a partitioned commit).
 *
 * Each dara arrays stores the local trees, the ghosts, face neighbor information
 * of the ghosts, face neihbor information of the trees and the attributes of the trees.
 * Furthermore we store for each tree and for each ghost to which data array they belong to.
 * So the data looks like:
 *
 * TODO: would be more logical to switch Ghost and Tree faces
 *
 * M_0:   | Trees | Ghosts | Ghost faces | Tree faces | Tree attributes | Ghost attributes
 * M_1:   | Trees | Ghosts | Ghost faces | Tree faces | Tree attributes | Ghost attributes
 *  .         .        .          .            .               .
 * M_n:   | Trees | Ghosts | Ghost faces | Tree faces | Tree attributes | Ghost attributes
 *
 * tree_to_proc:  | 0 | 0 | 1 | ... | n |  these are just random examples here
 * ghost_to_proc: | 0 | 1 | 2 | ... | n |
 *
 *
 * Each tree T stores an offset to its Tree faces, such that (char*)&T + offset is
 * a pointer to the faces array.
 * The same holds for the ghost.
 * Also each tree stores the number of attributes and an offset relative to itself
 * to the first attribute entry of that tree.
 *
 * Tree faces:
 *
 * The data of Tree faces looks for each tree:
 *
 * | Treeid1 Treeid2  ... | ttf1 ttf2 ... | padding |
 *
 * Where padding is a number of unused bytes that makes the whole block a multiple
 * of 4 Bytes.
 * Treeid is a t8_locidx_t storing the local tree id for local tree neighbors and
 * the local ghost id + num_local_trees for ghost neighbors.
 * For the encoding of ttf (tree to face) see \ref t8_ctree_struct_t, ttf entries are int8_t
 * and the offset of ttf1 can be calculated from the Tree faces offset and the
 * class of the tree.
 *
 * Ghost faces:
 *
 * | Treeid1 Treeid2 ... | ttf1 ttf2 ... | padding |
 *
 * Where padding is a number of unused bytes that makes the whole block a multiple
 * of sizeof (void*) Bytes.
 * Treeidj is a t8_gloidx_t storing the global tree id for all neighbors.
 * For the encoding of ttf (tree to face) see \ref t8_ctree_struct_t, ttf entries are int8_t
 * and the offset of ttf1 can be calculated from the Tree faces offset and the
 * class of the tree.
 * Tree attributes:
 *
 * The data of Tree attributes looks like:
 *
 * TODO: This description seems incomplete. Why is it not Attij_data?
 *
 * | Att00_descr | Att01_descr | ... | Att10_descr | ... | Attrend_descr | Att1_data | Att2_data | ... |
 *                TODO: maybe insert padding here ||
 * Where Attij_descr is a descriptor of the j-th attribute data of tree i storing
 * - an offset to Atti_data starting from Atti0_descr
 * - package id of the attribute (int)
 * - key of the attribute (int)
 * The data type is t8_attribute_info_struct_t
 *
 * Attrend_descr only stores the offset of the end of this attributes block
 * (like an imaginary very last attribute);
 * using this info the size of each attribute can be computed as the difference
 * of the sizes of two consecutive attributes.
 *
 * padding is a number of nonused bytes to make the size of the descr block
 * a multiple of four.
 *
 *  TODO: maybe padding after the last Att_data is useful too
 *  TODO: We may also need padding between the attributes.
 *
 */
 
/* allocate a t8_cmesh_tree struct and allocate memory for its entries.
 * No memory for ctrees or ghosts is allocated here */
/* TODO: document */
 
/* Given a tree return the beginning of its attributes block */
#define T8_TREE_FIRST_ATT(t) ((char *)(t) + (t)->att_offset)
 
/* Given a tree and an index i return the i-th attribute index of that tree */
#define T8_TREE_ATTR_INFO(t,i) ((t8_attribute_info_struct_t *) \
  ((char*)(t) + (t)->att_offset + \
  (i) * sizeof (t8_attribute_info_struct_t)))
 
/* Given a tree and an attribute info return the attribute */
#define T8_TREE_ATTR(t,ai) (T8_TREE_FIRST_ATT(t) + (ai)->attribute_offset)
 
/* Given a tree return its face_neighbor array */
#define T8_TREE_FACE(t) ((char *) (t) + (t)->neigh_offset)
 
/* Given a tree return irs tree_to_face array */
#define T8_TREE_TTF(t) (T8_TREE_FACE(t) + \
  t8_eclass_num_faces[(t)->eclass] * sizeof(t8_locidx_t))
 
/* Given a ghost return the beginning of its attribute block */
#define T8_GHOST_FIRST_ATT(g) T8_TREE_FIRST_ATT (g)
 
/* Given a ghost and an index i return the i-th attribute index of that ghost */
#define T8_GHOST_ATTR_INFO(g,i) T8_TREE_ATTR_INFO (g, i)
 
/* Given a ghost and an attribute info return the attribute */
#define T8_GHOST_ATTR(g,ai) T8_TREE_ATTR(g,ai)
 
/* Given a ghost return its face_neighbor array */
#define T8_GHOST_FACE(g) T8_TREE_FACE(g)
 
/* Given a ghost return its tree_to_face array */
#define T8_GHOST_TTF(g) (int8_t *) (T8_GHOST_FACE(g) + \
  t8_eclass_num_faces[(g)->eclass] * sizeof(t8_gloidx_t))
 
typedef struct
{
  t8_gloidx_t         global_id;
  t8_locidx_t         local_id; 
} t8_trees_glo_lo_hash_t;
 
void                t8_cmesh_trees_init (t8_cmesh_trees_t *ptrees,
                                         int num_procs, t8_locidx_t num_trees,
                                         t8_locidx_t num_ghosts);
 
t8_part_tree_t      t8_cmesh_trees_get_part (t8_cmesh_trees_t trees,
                                             int proc);
 
/* !!! This does only allocate memory for the trees and ghosts
 *     not yet for the face data and the attributes. See below !!!
 */
void                t8_cmesh_trees_start_part (t8_cmesh_trees_t trees,
                                               int proc,
                                               t8_locidx_t lfirst_tree,
                                               t8_locidx_t num_trees,
                                               t8_locidx_t lfirst_ghost,
                                               t8_locidx_t num_ghosts,
                                               int alloc);
 
void                t8_cmesh_trees_finish_part (t8_cmesh_trees_t trees,
                                                int proc);
 
void                t8_cmesh_trees_copy_toproc (t8_cmesh_trees_t trees_dest,
                                                t8_cmesh_trees_t trees_src,
                                                t8_locidx_t lnum_trees,
                                                t8_locidx_t lnum_ghosts);
 
void                t8_cmesh_trees_copy_part (t8_cmesh_trees_t trees_dest,
                                              int part_dest,
                                              t8_cmesh_trees_t trees_src,
                                              int part_src);
 
void                t8_cmesh_trees_add_tree (t8_cmesh_trees_t trees,
                                             t8_locidx_t ltree_id, int proc,
                                             t8_eclass_t eclass);
 
void                t8_cmesh_trees_add_ghost (t8_cmesh_trees_t trees,
                                              t8_locidx_t lghost_index,
                                              t8_gloidx_t gtree_id, int proc,
                                              t8_eclass_t eclass,
                                              t8_locidx_t num_local_trees);
 
void                t8_cmesh_trees_set_all_boundary (t8_cmesh_t cmesh,
                                                     t8_cmesh_trees_t trees);
 
void                t8_cmesh_trees_get_part_data (t8_cmesh_trees_t trees,
                                                  int proc,
                                                  t8_locidx_t *first_tree,
                                                  t8_locidx_t *num_trees,
                                                  t8_locidx_t *first_ghost,
                                                  t8_locidx_t *num_ghosts);
 
/* TODO: This function returns NULL if the tree is not present.
 *       So far no error checking is done here. */
t8_ctree_t          t8_cmesh_trees_get_tree (t8_cmesh_trees_t trees,
                                             t8_locidx_t ltree);
 
t8_ctree_t          t8_cmesh_trees_get_tree_ext (t8_cmesh_trees_t trees,
                                                 t8_locidx_t ltree_id,
                                                 t8_locidx_t **face_neigh,
                                                 int8_t **ttf);
 
t8_locidx_t         t8_cmesh_trees_get_face_info (t8_cmesh_trees_t trees,
                                                  t8_locidx_t ltreeid,
                                                  int face, int8_t *ttf);
 
t8_locidx_t         t8_cmesh_trees_get_face_neighbor (const t8_ctree_t tree,
                                                      const int face);
 
t8_locidx_t         t8_cmesh_trees_get_face_neighbor_ext (const t8_ctree_t
                                                          tree,
                                                          const int face,
                                                          int8_t *ttf);
 
t8_gloidx_t         t8_cmesh_trees_get_ghost_face_neighbor_ext (const
                                                                t8_cghost_t
                                                                ghost,
                                                                const int
                                                                face,
                                                                int8_t *ttf);
 
/* TODO: This function returns NULL if the ghost is not present.
 *       So far no error checking is done here. */
t8_cghost_t         t8_cmesh_trees_get_ghost (t8_cmesh_trees_t trees,
                                              t8_locidx_t lghost);
 
t8_cghost_t         t8_cmesh_trees_get_ghost_ext (t8_cmesh_trees_t trees,
                                                  t8_locidx_t lghost_id,
                                                  t8_gloidx_t **face_neigh,
                                                  int8_t **ttf);
 
t8_locidx_t         t8_cmesh_trees_get_ghost_local_id (t8_cmesh_trees_t trees,
                                                       t8_gloidx_t global_id);
 
/* TODO: document.
 * returns the complete size in bytes needed to store all information */
size_t              t8_cmesh_trees_size (t8_cmesh_trees_t trees);
 
void                t8_cmesh_trees_init_attributes (t8_cmesh_trees_t trees,
                                                    t8_locidx_t ltree_id,
                                                    size_t num_attributes,
                                                    size_t attr_bytes);
 
void               *t8_cmesh_trees_get_attribute (t8_cmesh_trees_t trees,
                                                  t8_locidx_t ltree_id,
                                                  int package_id, int key,
                                                  size_t *size, int is_ghost);
 
size_t              t8_cmesh_trees_attribute_size (t8_ctree_t tree);
 
size_t              t8_cmesh_trees_ghost_attribute_size (t8_cghost_t ghost);
 
/* TODO: Currently there is a bug that forces us to give each tree an attribute */
/* TODO: this uses char * and cmesh_set_attribute uses void *. Unify! */
/* attr_tree_index is index of attr in tree's attribute array.
 * We assume that the attributes are already sorted! */
void                t8_cmesh_trees_add_attribute (t8_cmesh_trees_t trees,
                                                  int proc,
                                                  t8_stash_attribute_struct_t
                                                  *attr, t8_locidx_t tree_id,
                                                  size_t index);
 
size_t              t8_cmesh_trees_get_numproc (t8_cmesh_trees_t trees);
 
int8_t              t8_cmesh_tree_to_face_encode (const int dimension,
                                                  const t8_locidx_t face,
                                                  const int orientation);
 
void                t8_cmesh_tree_to_face_decode (const int dimension,
                                                  const int8_t tree_to_face,
                                                  int *face,
                                                  int *orientation);
 
/* TODO: To fit to the interface a trees struct is given as parameter here,
 *       however we could just take the one associated to the cmesh given.*/
void                t8_cmesh_trees_print (t8_cmesh_t cmesh,
                                          t8_cmesh_trees_t trees);
 
void                t8_cmesh_trees_bcast (t8_cmesh_t cmesh_in, int root,
                                          sc_MPI_Comm comm);
 
int                 t8_cmesh_trees_is_face_consistend (t8_cmesh_t cmesh,
                                                       t8_cmesh_trees_t
                                                       trees);
 
int                 t8_cmesh_trees_is_equal (t8_cmesh_t cmesh,
                                             t8_cmesh_trees_t trees_a,
                                             t8_cmesh_trees_t trees_b);
 
void                t8_cmesh_trees_destroy (t8_cmesh_trees_t *trees);
 
T8_EXTERN_C_END ();
 
#endif /* !T8_CMESH_PART_TREE_H */