p4est  1.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs | Functions | Variables
p4est.h File Reference

The top-level 2D p4est interface. More...

#include <p4est_connectivity.h>

Go to the source code of this file.

Data Structures

struct  p4est_quadrant_t
 The 2D quadrant datatype. More...
 
union  p4est_quadrant_t::p4est_quadrant_data
 
struct  p4est_tree_t
 The p4est tree datatype. More...
 
struct  p4est_t
 The p4est forest datatype. More...
 

Macros

#define P4EST_MAXLEVEL   30
 The finest level of the quadtree for representing nodes.
 
#define P4EST_QMAXLEVEL   29
 The finest level of the quadtree for representing quadrants.
 
#define P4EST_ROOT_LEN   ((p4est_qcoord_t) 1 << P4EST_MAXLEVEL)
 The length of a side of the root quadrant.
 
#define P4EST_QUADRANT_LEN(l)   ((p4est_qcoord_t) 1 << (P4EST_MAXLEVEL - (l)))
 The length of a quadrant of level l.
 
#define P4EST_LAST_OFFSET(l)   (P4EST_ROOT_LEN - P4EST_QUADRANT_LEN (l))
 The offset of the highest (farthest from the origin) quadrant at level l.
 
#define P4EST_QUADRANT_INIT(q)   ((void) memset ((q), -1, sizeof (p4est_quadrant_t)))
 set statically allocated quadrant to defined values
 

Typedefs

typedef 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. More...
 
typedef int(* p4est_refine_t )(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)
 Callback function prototype to decide for refinement. More...
 
typedef int(* p4est_coarsen_t )(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrants[])
 Callback function prototype to decide for coarsening. More...
 
typedef int(* p4est_weight_t )(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)
 Callback function prototype to calculate weights for partitioning. More...
 

Functions

size_t p4est_memory_used (p4est_t *p4est)
 Calculate memory usage of a forest structure. More...
 
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. More...
 
p4est_tp4est_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. More...
 
void p4est_destroy (p4est_t *p4est)
 Destroy a p4est. More...
 
p4est_tp4est_copy (p4est_t *input, int copy_data)
 Make a deep copy of a p4est. More...
 
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. More...
 
void p4est_refine (p4est_t *p4est, int refine_recursive, p4est_refine_t refine_fn, p4est_init_t init_fn)
 Refine a forest. More...
 
void p4est_coarsen (p4est_t *p4est, int coarsen_recursive, p4est_coarsen_t coarsen_fn, p4est_init_t init_fn)
 Coarsen a forest. More...
 
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. More...
 
void p4est_partition (p4est_t *p4est, int allow_for_coarsening, p4est_weight_t weight_fn)
 Equally partition the forest. More...
 
unsigned p4est_checksum (p4est_t *p4est)
 Compute the checksum for a forest. More...
 
void p4est_save (const char *filename, p4est_t *p4est, int save_data)
 Save the complete connectivity/p4est data to disk. More...
 
p4est_tp4est_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. More...
 
static p4est_tree_tp4est_tree_array_index (sc_array_t *array, p4est_topidx_t it)
 Return a pointer to an array element indexed by a p4est_topidx_t. More...
 
static p4est_quadrant_tp4est_quadrant_array_index (sc_array_t *array, size_t it)
 Return a pointer to a quadrant array element indexed by a size_t. More...
 
static p4est_quadrant_tp4est_quadrant_array_push (sc_array_t *array)
 Call sc_array_push for a quadrant array. More...
 
static p4est_quadrant_tp4est_quadrant_mempool_alloc (sc_mempool_t *mempool)
 Call sc_mempool_alloc for a mempool creating quadrants. More...
 
static p4est_quadrant_tp4est_quadrant_list_pop (sc_list_t *list)
 Call sc_list pop for a quadrant array. More...
 

Variables

void * P4EST_DATA_UNINITIALIZED
 

Detailed Description

The top-level 2D p4est interface.

Typedef Documentation

typedef int(* p4est_coarsen_t)(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrants[])

Callback function prototype to decide for coarsening.

Parameters
[in]p4estthe forest
[in]which_treethe tree containing quadrant
[in]quadrantsPointers to 4 siblings in Morton ordering.
Returns
nonzero if the quadrants shall be replaced with their parent.
typedef 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.

Parameters
[in]p4estthe forest
[in]which_treethe tree containing quadrant
[in,out]quadrantthe quadrant to be initialized: if data_size > 0, the data to be initialized is at quadrant->p.user_data; otherwise, the non-pointer user data (such as quadrant->p.user_int) can be initialized
typedef int(* p4est_refine_t)(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)

Callback function prototype to decide for refinement.

Parameters
[in]p4estthe forest
[in]which_treethe tree containing quadrant
[in]quadrantthe quadrant that may be refined
Returns
nonzero if the quadrant shall be refined.
typedef int(* p4est_weight_t)(p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)

Callback function prototype to calculate weights for partitioning.

Parameters
[in]p4estthe forest
[in]which_treethe tree containing quadrant
Returns
a 32bit integer >= 0 as the quadrant weight.
Note
Global sum of weights must fit into a 64bit integer.

Function Documentation

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.

Parameters
[in,out]p4estThe p4est to be worked on.
[in]btypeBalance type (face or corner/full). Corner balance is almost never required when discretizing a PDE; just causes smoother mesh grading.
[in]init_fnCallback function to initialize the user_data which is already allocated automatically.
unsigned p4est_checksum ( p4est_t p4est)

Compute the checksum for a forest.

Based on quadrant arrays only. It is independent of partition and mpisize.

Returns
Returns the checksum on processor 0 only. 0 on other processors.
void p4est_coarsen ( p4est_t p4est,
int  coarsen_recursive,
p4est_coarsen_t  coarsen_fn,
p4est_init_t  init_fn 
)

Coarsen a forest.

Parameters
[in,out]p4estThe forest is changed in place.
[in]coarsen_recursiveBoolean to decide on recursive coarsening.
[in]coarsen_fnCallback function that returns true if a family of quadrants shall be coarsened
[in]init_fnCallback function to initialize the user_data which is already allocated automatically.
p4est_t* p4est_copy ( p4est_t input,
int  copy_data 
)

Make a deep copy of a p4est.

The connectivity is not duplicated. Copying of quadrant user data is optional. If old and new data sizes are 0, the user_data field is copied regardless. The inspect member of the copy is set to NULL.

Parameters
[in]copy_dataIf true, data are copied. If false, data_size is set to 0.
Returns
Returns a valid p4est that does not depend on the input.
void p4est_destroy ( p4est_t p4est)

Destroy a p4est.

Note
The connectivity structure is not destroyed with the p4est.
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.

This is a collective operation that all MPI processes need to call. All processes read from the same file, so the filename given needs to be identical over all parallel invocations.

By default, a file can only be loaded with the same number of processors that it was stored with. The defaults can be changed with p4est_load_ext() in p4est_extended.h.

Parameters
[in]filenameName of the file to read.
[in]mpicommA valid MPI communicator.
[in]data_sizeSize of data for each quadrant which can be zero. Then user_data_pool is set to NULL. If data_size is zero, load_data is ignored.
[in]load_dataIf true, the element data is loaded. This is only permitted if the saved data size matches. If false, the stored data size is ignored.
[in]user_pointerAssign to the user_pointer member of the p4est before init_fn is called the first time.
[out]connectivityConnectivity must be destroyed separately.
Returns
Returns a valid forest structure. A pointer to a valid connectivity structure is returned through the last argument.
Note
Aborts on file errors or invalid file contents.
size_t p4est_memory_used ( p4est_t p4est)

Calculate memory usage of a forest structure.

The connectivity structure is not counted since it is not owned; use p4est_connectivity_memory_usage (p4est->connectivity).

Parameters
[in]p4estForest structure.
Returns
Memory used in bytes.
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.

The new forest consists of equi-partitioned root quadrants. When there are more processors than trees, some processors are empty.

Parameters
[in]mpicommA valid MPI communicator.
[in]connectivityThis is the connectivity information that the forest is built with. Note the p4est does not take ownership of the memory.
[in]data_sizeThis is the size of data for each quadrant which can be zero. Then user_data_pool is set to NULL.
[in]init_fnCallback function to initialize the user_data which is already allocated automatically.
[in]user_pointerAssign to the user_pointer member of the p4est before init_fn is called the first time.
Returns
This returns a valid forest.
Note
The connectivity structure must not be destroyed during the lifetime of this forest.
void p4est_partition ( p4est_t p4est,
int  allow_for_coarsening,
p4est_weight_t  weight_fn 
)

Equally partition the forest.

The partition can be by element count or by a user-defined weight.

The forest will be partitioned between processors such that they have an approximately equal number of quadrants (or sum of weights).

Parameters
[in,out]p4estThe forest that will be partitioned.
[in]allow_for_coarseningSlightly modify partition such that quadrant families are not split between ranks.
[in]weight_fnA weighting function or NULL for uniform partitioning.
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.

Parameters
[in]connectivityConnectivity must provide the vertices.
[in]treeidIdentify the tree that contains x, y.
[in]x,yQuadrant coordinates relative to treeid.
[out]vxyTransformed coordinates in vertex space.
static p4est_quadrant_t* p4est_quadrant_array_index ( sc_array_t array,
size_t  it 
)
inlinestatic

Return a pointer to a quadrant array element indexed by a size_t.

static p4est_quadrant_t* p4est_quadrant_array_push ( sc_array_t array)
inlinestatic

Call sc_array_push for a quadrant array.

static p4est_quadrant_t* p4est_quadrant_list_pop ( sc_list_t list)
inlinestatic

Call sc_list pop for a quadrant array.

static p4est_quadrant_t* p4est_quadrant_mempool_alloc ( sc_mempool_t mempool)
inlinestatic

Call sc_mempool_alloc for a mempool creating quadrants.

void p4est_refine ( p4est_t p4est,
int  refine_recursive,
p4est_refine_t  refine_fn,
p4est_init_t  init_fn 
)

Refine a forest.

Parameters
[in,out]p4estThe forest is changed in place.
[in]refine_recursiveBoolean to decide on recursive refinement.
[in]refine_fnCallback function that must return true if a quadrant shall be refined. If refine_recursive is true, refine_fn is called for every existing and newly created quadrant. Otherwise, it is called for every existing quadrant. It is possible that a refinement request made by the callback is ignored. To catch this case, you can examine whether init_fn gets called, or use p4est_refine_ext in p4est_extended.h and examine whether replace_fn gets called.
[in]init_fnCallback function to initialize the user_data of newly created quadrants, which is already allocated. This function pointer may be NULL.
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.

When the data size is changed the quadrant data is freed and allocated. The initialization callback is invoked on each quadrant. Old user_data content is disregarded.

Parameters
[in]data_sizeThis is the size of data for each quadrant which can be zero. Then user_data_pool is set to NULL.
[in]init_fnCallback function to initialize the user_data which is already allocated automatically. May be NULL.
[in]user_pointerAssign to the user_pointer member of the p4est before init_fn is called the first time.
void p4est_save ( const char *  filename,
p4est_t p4est,
int  save_data 
)

Save the complete connectivity/p4est data to disk.

This is a collective operation that all MPI processes need to call. All processes write into the same file, so the filename given needs to be identical over all parallel invocations.

By default, we write the current processor count and partition into the file header. This makes the file depend on mpisize. For changing this see p4est_save_ext() in p4est_extended.h.

Parameters
[in]filenameName of the file to write.
[in]p4estValid forest structure.
[in]save_dataIf true, the element data is saved. Otherwise, a data size of 0 is saved.
Note
Aborts on file errors.
If p4est is not configured to use MPI-IO, some processes return from this function before the file is complete, in which case immediate read-access to the file may require a call to sc_MPI_Barrier.
static p4est_tree_t* p4est_tree_array_index ( sc_array_t array,
p4est_topidx_t  it 
)
inlinestatic

Return a pointer to an array element indexed by a p4est_topidx_t.

Parameters
[in]indexneeds to be in [0]..[elem_count-1].