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 whereas 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 arose 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:
 *
 * For each tree the data of the tree faces (where F is the number of faces of the tree) looks like this:
 *
 * | Treeid1 Treeid2  ... TreeidF | ttf1 ttf2 ... ttfN | 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 ... TreeidF | ttf1 ttf2 ... ttfF | 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, where N is the total number of attributes:
 * The Attributes do not necessarily need to be sorted in a particular way, as they are
 * accessed by offsets in the Att_descr.
 *
 * | Att00_descr | Att01_descr | ... Att0 A_0_descr| Att10_descr | ... | AttrT A_T | Att0_data | Att2_data | ... AttN_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 Attk_data starting from Attij_descr, where k is the index in the dataarray.
 *    The actual data is put there in the order of the attribute descriptors, but this is not necessitated by the layout.
 * - 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 (const t8_cmesh_trees_t trees, const 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);
 
size_t
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 (const t8_cmesh_trees_t trees, const t8_locidx_t ltree_id, const int package_id,
                              const 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);
 
void
t8_cmesh_trees_add_ghost_attribute (t8_cmesh_trees_t trees, int proc, t8_stash_attribute_struct_t *attr,
                                    t8_locidx_t local_ghost_id, size_t index, size_t *attribute_data_offset);
 
size_t
t8_cmesh_trees_get_numproc (const 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_consistent (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 */