p4est  1.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
p4est.h
Go to the documentation of this file.
1 /*
2  This file is part of p4est.
3  p4est is a C library to manage a collection (a forest) of multiple
4  connected adaptive quadtrees or octrees in parallel.
5 
6  Copyright (C) 2010 The University of Texas System
7  Written by Carsten Burstedde, Lucas C. Wilcox, and Tobin Isaac
8 
9  p4est is free software; you can redistribute it and/or modify
10  it under the terms of the GNU General Public License as published by
11  the Free Software Foundation; either version 2 of the License, or
12  (at your option) any later version.
13 
14  p4est is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  GNU General Public License for more details.
18 
19  You should have received a copy of the GNU General Public License
20  along with p4est; if not, write to the Free Software Foundation, Inc.,
21  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 */
23 
36 #ifndef P4EST_H
37 #define P4EST_H
38 
39 #ifdef P4EST_TO_P8EST_H
40 #error "The include files p4est.h and p4est_to_p8est.h cannot be combined"
41 #endif
42 
43 /* p4est_connectivity.h includes p4est_base.h sc_containers.h */
44 #include <p4est_connectivity.h>
45 
46 SC_EXTERN_C_BEGIN;
47 
49 #define P4EST_MAXLEVEL 30
50 
52 #define P4EST_QMAXLEVEL 29
53 
55 #define P4EST_ROOT_LEN ((p4est_qcoord_t) 1 << P4EST_MAXLEVEL)
56 
58 #define P4EST_QUADRANT_LEN(l) ((p4est_qcoord_t) 1 << (P4EST_MAXLEVEL - (l)))
59 
62 #define P4EST_LAST_OFFSET(l) (P4EST_ROOT_LEN - P4EST_QUADRANT_LEN (l))
63 
65 typedef struct p4est_quadrant
66 {
70  int8_t level,
71  pad8;
72  int16_t pad16;
74  {
75  void *user_data;
76  long user_long;
77  int user_int;
82  struct
83  {
84  p4est_topidx_t which_tree;
85  int owner_rank;
86  }
87  piggy1;
88  struct
89  {
90  p4est_topidx_t which_tree;
91  p4est_topidx_t from_tree;
92  }
93  piggy2;
95  struct
96  {
97  p4est_topidx_t which_tree;
98  p4est_locidx_t local_num;
99  }
100  piggy3;
102  }
103  p;
104 }
106 
108 typedef struct p4est_tree
109 {
111  p4est_quadrant_t first_desc,
112  last_desc;
116  p4est_locidx_t quadrants_per_level[P4EST_MAXLEVEL + 1];
118  int8_t maxlevel;
119 }
121 
126 typedef struct p4est_inspect p4est_inspect_t;
127 
129 typedef struct p4est
130 {
131  sc_MPI_Comm mpicomm;
132  int mpisize,
133  mpirank;
134  size_t data_size;
136  void *user_pointer;
159  /* WARNING: This is NULL if data size
160  equals zero. */
164 }
165 p4est_t;
166 
173 size_t p4est_memory_used (p4est_t * p4est);
174 
184 typedef void (*p4est_init_t) (p4est_t * p4est,
185  p4est_topidx_t which_tree,
186  p4est_quadrant_t * quadrant);
187 
194 typedef int (*p4est_refine_t) (p4est_t * p4est,
195  p4est_topidx_t which_tree,
196  p4est_quadrant_t * quadrant);
197 
204 typedef int (*p4est_coarsen_t) (p4est_t * p4est,
205  p4est_topidx_t which_tree,
206  p4est_quadrant_t * quadrants[]);
207 
214 typedef int (*p4est_weight_t) (p4est_t * p4est,
215  p4est_topidx_t which_tree,
216  p4est_quadrant_t * quadrant);
217 
218 extern void *P4EST_DATA_UNINITIALIZED;
219 
221 #define P4EST_QUADRANT_INIT(q) \
222  ((void) memset ((q), -1, sizeof (p4est_quadrant_t)))
223 
231  connectivity,
232  p4est_topidx_t treeid,
233  p4est_qcoord_t x,
234  p4est_qcoord_t y, double vxyz[3]);
235 
256 p4est_t *p4est_new (sc_MPI_Comm mpicomm,
257  p4est_connectivity_t * connectivity,
258  size_t data_size,
259  p4est_init_t init_fn, void *user_pointer);
260 
265 void p4est_destroy (p4est_t * p4est);
266 
277 p4est_t *p4est_copy (p4est_t * input, int copy_data);
278 
292 void p4est_reset_data (p4est_t * p4est, size_t data_size,
293  p4est_init_t init_fn,
294  void *user_pointer);
295 
312 void p4est_refine (p4est_t * p4est,
313  int refine_recursive,
315  p4est_init_t init_fn);
316 
325 void p4est_coarsen (p4est_t * p4est,
326  int coarsen_recursive,
327  p4est_coarsen_t coarsen_fn,
328  p4est_init_t init_fn);
329 
338 void p4est_balance (p4est_t * p4est,
339  p4est_connect_type_t btype,
340  p4est_init_t init_fn);
341 
354 void p4est_partition (p4est_t * p4est,
355  int allow_for_coarsening,
356  p4est_weight_t weight_fn);
357 
362 unsigned p4est_checksum (p4est_t * p4est);
363 
384 void p4est_save (const char *filename, p4est_t * p4est,
385  int save_data);
386 
413 p4est_t *p4est_load (const char *filename, sc_MPI_Comm mpicomm,
414  size_t data_size, int load_data,
415  void *user_pointer,
416  p4est_connectivity_t ** connectivity);
417 
421 /*@unused@*/
422 static inline p4est_tree_t *
424 {
425  P4EST_ASSERT (array->elem_size == sizeof (p4est_tree_t));
426  P4EST_ASSERT (it >= 0 && (size_t) it < array->elem_count);
427 
428  return (p4est_tree_t *) (array->array +
429  sizeof (p4est_tree_t) * (size_t) it);
430 }
431 
433 /*@unused@*/
434 static inline p4est_quadrant_t *
436 {
437  P4EST_ASSERT (array->elem_size == sizeof (p4est_quadrant_t));
438  P4EST_ASSERT (it < array->elem_count);
439 
440  return (p4est_quadrant_t *) (array->array + sizeof (p4est_quadrant_t) * it);
441 }
442 
444 /*@unused@*/
445 static inline p4est_quadrant_t *
447 {
448  P4EST_ASSERT (array->elem_size == sizeof (p4est_quadrant_t));
449 
450  return (p4est_quadrant_t *) sc_array_push (array);
451 }
452 
454 /*@unused@*/
455 static inline p4est_quadrant_t *
457 {
458  P4EST_ASSERT (mempool->elem_size == sizeof (p4est_quadrant_t));
459 
460  return (p4est_quadrant_t *) sc_mempool_alloc (mempool);
461 }
462 
464 /*@unused@*/
465 static inline p4est_quadrant_t *
467 {
468  return (p4est_quadrant_t *) sc_list_pop (list);
469 }
470 
471 SC_EXTERN_C_END;
472 
473 #endif /* !P4EST_H */
void p4est_destroy(p4est_t *p4est)
Destroy a p4est.
Definition: p4est.c:483
p4est_t * p4est_new(sc_MPI_Comm mpicomm, p4est_connectivity_t *connectivity, size_t data_size, p4est_init_t init_fn, void *user_pointer)
Create a new forest.
Definition: p4est.c:173
void p4est_partition(p4est_t *p4est, int allow_for_coarsening, p4est_weight_t weight_fn)
Equally partition the forest.
Definition: p4est.c:2367
size_t p4est_memory_used(p4est_t *p4est)
Calculate memory usage of a forest structure.
Definition: p4est.c:148
int32_t p4est_qcoord_t
Typedef for quadrant coordinates.
Definition: p4est_base.h:53
unsigned p4est_checksum(p4est_t *p4est)
Compute the checksum for a forest.
Definition: p4est.c:3147
int16_t pad16
padding
Definition: p4est.h:72
p4est_topidx_t last_local_tree
0-based index of last local tree, must be -2 for an empty processor
Definition: p4est.h:142
size_t elem_size
size of a single element
Definition: sc_containers.h:499
void p4est_coarsen(p4est_t *p4est, int coarsen_recursive, p4est_coarsen_t coarsen_fn, p4est_init_t init_fn)
Coarsen a forest.
Definition: p4est.c:890
void p4est_balance(p4est_t *p4est, p4est_connect_type_t btype, p4est_init_t init_fn)
2:1 balance the size differences of neighboring elements in a forest.
Definition: p4est.c:1190
char * array
linear array to store elements
Definition: sc_containers.h:104
void p4est_save(const char *filename, p4est_t *p4est, int save_data)
Save the complete connectivity/p4est data to disk.
Definition: p4est.c:3183
#define p4est_inspect_t
Data pertaining to selecting, inspecting, and profiling algorithms.
Definition: p4est_to_p8est.h:101
sc_array_t * trees
array of all trees
Definition: p4est.h:156
size_t elem_size
size of a single element
Definition: sc_containers.h:95
void * user_pointer
convenience pointer for users, never touched by p4est
Definition: p4est.h:136
p4est_qcoord_t y
coordinates
Definition: p4est.h:68
The sc_list object provides a linked list.
Definition: sc_containers.h:587
p4est_topidx_t which_tree
the tree containing the quadrant (used in auxiliary octants such as the ghost octants in p4est_ghost_...
Definition: p4est.h:78
void p4est_reset_data(p4est_t *p4est, size_t data_size, p4est_init_t init_fn, void *user_pointer)
Reset user pointer and element data.
Definition: p4est.c:596
void p4est_refine(p4est_t *p4est, int refine_recursive, p4est_refine_t refine_fn, p4est_init_t init_fn)
Refine a forest.
Definition: p4est.c:644
p4est_quadrant_t * global_first_position
first smallest possible quad for each process and 1 beyond
Definition: p4est.h:152
static int refine_fn(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)
Callback function to decide on refinement.
Definition: p4est_step1.c:59
sc_mempool_t * quadrant_pool
memory allocator for temporary quadrants
Definition: p4est.h:161
Data pertaining to selecting, inspecting, and profiling algorithms.
Definition: p4est_extended.h:56
int64_t p4est_gloidx_t
Typedef for globally unique indexing of quadrants.
Definition: p4est_base.h:84
#define P4EST_MAXLEVEL
The finest level of the quadtree for representing nodes.
Definition: p4est.h:49
The p4est forest datatype.
Definition: p4est.h:129
p4est_inspect_t * inspect
algorithmic switches
Definition: p4est.h:163
static void * sc_array_push(sc_array_t *array)
Enlarge an array by one element.
Definition: sc_containers.h:485
static p4est_quadrant_t * p4est_quadrant_list_pop(sc_list_t *list)
Call sc_list pop for a quadrant array.
Definition: p4est.h:466
This structure holds the 2D inter-tree connectivity information.
Definition: p4est_connectivity.h:139
int8_t pad8
padding
Definition: p4est.h:70
p4est_t * p4est_load(const char *filename, sc_MPI_Comm mpicomm, size_t data_size, int load_data, void *user_pointer, p4est_connectivity_t **connectivity)
Load the complete connectivity/p4est structure from disk.
Definition: p4est.c:3419
void p4est_qcoord_to_vertex(p4est_connectivity_t *connectivity, p4est_topidx_t treeid, p4est_qcoord_t x, p4est_qcoord_t y, double vxyz[3])
Transform a quadrant coordinate into the space spanned by tree vertices.
Definition: p4est.c:79
sc_array_t quadrants
locally stored quadrants
Definition: p4est.h:110
static p4est_quadrant_t * p4est_quadrant_array_push(sc_array_t *array)
Call sc_array_push for a quadrant array.
Definition: p4est.h:446
long user_long
never changed by p4est
Definition: p4est.h:76
The sc_array object provides a large array of equal-size elements.
Definition: sc_containers.h:92
int(* p4est_coarsen_t)(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrants[])
Callback function prototype to decide for coarsening.
Definition: p4est.h:204
p4est_connectivity_t * connectivity
connectivity structure, not owned
Definition: p4est.h:155
void * sc_list_pop(sc_list_t *list)
Remove an element from the front of the list.
p4est_connect_type_t
Characterize a type of adjacency.
Definition: p4est_connectivity.h:77
static p4est_quadrant_t * p4est_quadrant_array_index(sc_array_t *array, size_t it)
Return a pointer to a quadrant array element indexed by a size_t.
Definition: p4est.h:435
The p4est tree datatype.
Definition: p4est.h:108
void(* p4est_init_t)(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)
Callback function prototype to initialize the quadrant's user data.
Definition: p4est.h:184
sc_mempool_t * user_data_pool
memory allocator for user data
Definition: p4est.h:158
int user_int
never changed by p4est
Definition: p4est.h:77
static p4est_quadrant_t * p4est_quadrant_mempool_alloc(sc_mempool_t *mempool)
Call sc_mempool_alloc for a mempool creating quadrants.
Definition: p4est.h:456
int32_t p4est_topidx_t
Typedef for counting topological entities (trees, tree vertices).
Definition: p4est_base.h:63
size_t data_size
size of per-quadrant p.user_data (see p4est_quadrant_t::p4est_quadrant_data::user_data) ...
Definition: p4est.h:134
int32_t p4est_locidx_t
Typedef for processor-local indexing of quadrants and nodes.
Definition: p4est_base.h:74
p4est_locidx_t local_num_quadrants
number of quadrants on all trees on this processor
Definition: p4est.h:145
static p4est_tree_t * p4est_tree_array_index(sc_array_t *array, p4est_topidx_t it)
Return a pointer to an array element indexed by a p4est_topidx_t.
Definition: p4est.h:423
int mpisize
number of MPI processes
Definition: p4est.h:132
void * user_data
never changed by p4est
Definition: p4est.h:75
p4est_locidx_t quadrants_offset
cumulative sum over earlier trees on this processor (locals only)
Definition: p4est.h:113
p4est_quadrant_t last_desc
last local descendant
Definition: p4est.h:111
The coarse topological description of the forest.
p4est_t * p4est_copy(p4est_t *input, int copy_data)
Make a deep copy of a p4est.
Definition: p4est.c:517
int(* p4est_refine_t)(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)
Callback function prototype to decide for refinement.
Definition: p4est.h:194
static void * sc_mempool_alloc(sc_mempool_t *mempool)
Allocate a single element.
Definition: sc_containers.h:535
The sc_mempool object provides a large pool of equal-size elements.
Definition: sc_containers.h:496
The 2D quadrant datatype.
Definition: p4est.h:65
p4est_topidx_t first_local_tree
0-based index of first local tree, must be -1 for an empty processor
Definition: p4est.h:139
p4est_gloidx_t global_num_quadrants
number of quadrants on all trees on all processors
Definition: p4est.h:147
int8_t maxlevel
highest local quadrant level
Definition: p4est.h:118
int(* p4est_weight_t)(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)
Callback function prototype to calculate weights for partitioning.
Definition: p4est.h:214
sc_MPI_Comm mpicomm
MPI communicator.
Definition: p4est.h:131
p4est_gloidx_t * global_first_quadrant
first global quadrant index for each process and 1 beyond
Definition: p4est.h:149