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

The top-level 3D p8est interface. More...

#include <p8est_connectivity.h>

Go to the source code of this file.

Data Structures

struct  p8est_quadrant_t
 The 3D quadrant (i.e. More...
 
union  p8est_quadrant_t::p8est_quadrant_data
 
struct  p8est_tree_t
 The p8est tree datatype. More...
 
struct  p8est_t
 The p8est forest datatype. More...
 

Macros

#define P8EST_MAXLEVEL   19
 The finest level of the octree for representing nodes.
 
#define P8EST_QMAXLEVEL   18
 The finest level of the octree for representing octants.
 
#define P8EST_ROOT_LEN   ((p4est_qcoord_t) 1 << P8EST_MAXLEVEL)
 The length of a side of the root quadrant.
 
#define P8EST_QUADRANT_LEN(l)   ((p4est_qcoord_t) 1 << (P8EST_MAXLEVEL - (l)))
 The length of a quadrant of level l.
 
#define P8EST_LAST_OFFSET(l)   (P8EST_ROOT_LEN - P8EST_QUADRANT_LEN (l))
 The offset of the highest (farthest from the origin) quadrant at level l.
 
#define P8EST_QUADRANT_INIT(q)   ((void) memset ((q), -1, sizeof (p8est_quadrant_t)))
 set statically allocated quadrant to defined values
 

Typedefs

typedef void(* p8est_init_t )(p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)
 Callback function prototype to initialize the quadrant's user data. More...
 
typedef int(* p8est_refine_t )(p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)
 Callback function prototype to decide for refinement. More...
 
typedef int(* p8est_coarsen_t )(p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrants[])
 Callback function prototype to decide for coarsening. More...
 
typedef int(* p8est_weight_t )(p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)
 Callback function prototype to calculate weights for partitioning. More...
 

Functions

size_t p8est_memory_used (p8est_t *p8est)
 Calculate memory usage of a forest structure. More...
 
void p8est_qcoord_to_vertex (p8est_connectivity_t *connectivity, p4est_topidx_t treeid, p4est_qcoord_t x, p4est_qcoord_t y, p4est_qcoord_t z, double vxyz[3])
 Transform a quadrant coordinate into the space spanned by tree vertices. More...
 
p8est_tp8est_new (sc_MPI_Comm mpicomm, p8est_connectivity_t *connectivity, size_t data_size, p8est_init_t init_fn, void *user_pointer)
 Create a new forest. More...
 
void p8est_destroy (p8est_t *p8est)
 Destroy a p8est. More...
 
p8est_tp8est_copy (p8est_t *input, int copy_data)
 Make a deep copy of a p8est. More...
 
void p8est_reset_data (p8est_t *p8est, size_t data_size, p8est_init_t init_fn, void *user_pointer)
 Reset user pointer and element data. More...
 
void p8est_refine (p8est_t *p8est, int refine_recursive, p8est_refine_t refine_fn, p8est_init_t init_fn)
 Refine a forest. More...
 
void p8est_coarsen (p8est_t *p8est, int coarsen_recursive, p8est_coarsen_t coarsen_fn, p8est_init_t init_fn)
 Coarsen a forest. More...
 
void p8est_balance (p8est_t *p8est, p8est_connect_type_t btype, p8est_init_t init_fn)
 2:1 balance the size differences of neighboring elements in a forest. More...
 
void p8est_partition (p8est_t *p8est, int allow_for_coarsening, p8est_weight_t weight_fn)
 Equally partition the forest. More...
 
unsigned p8est_checksum (p8est_t *p8est)
 Compute the checksum for a forest. More...
 
void p8est_save (const char *filename, p8est_t *p8est, int save_data)
 Save the complete connectivity/p8est data to disk. More...
 
p8est_tp8est_load (const char *filename, sc_MPI_Comm mpicomm, size_t data_size, int load_data, void *user_pointer, p8est_connectivity_t **connectivity)
 Load the complete connectivity/p8est structure from disk. More...
 
static p8est_tree_tp8est_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 p8est_quadrant_tp8est_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 p8est_quadrant_tp8est_quadrant_array_push (sc_array_t *array)
 Call sc_array_push for a quadrant array. More...
 
static p8est_quadrant_tp8est_quadrant_mempool_alloc (sc_mempool_t *mempool)
 Call sc_mempool_alloc for a mempool creating quadrants. More...
 
static p8est_quadrant_tp8est_quadrant_list_pop (sc_list_t *list)
 Call sc_list pop for a quadrant array. More...
 

Variables

void * P8EST_DATA_UNINITIALIZED
 

Detailed Description

The top-level 3D p8est interface.

Typedef Documentation

typedef int(* p8est_coarsen_t)(p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrants[])

Callback function prototype to decide for coarsening.

Parameters
[in]p8estthe forest
[in]which_treethe tree containing quadrant
[in]quadrantsPointers to 8 siblings in Morton ordering.
Returns
nonzero if the quadrants shall be replaced with their parent.
typedef void(* p8est_init_t)(p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)

Callback function prototype to initialize the quadrant's user data.

Parameters
[in]p8estthe 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(* p8est_refine_t)(p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)

Callback function prototype to decide for refinement.

Parameters
[in]p8estthe forest
[in]which_treethe tree containing quadrant
[in]quadrantthe quadrant that may be refined
Returns
nonzero if the quadrant shall be refined.
typedef int(* p8est_weight_t)(p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)

Callback function prototype to calculate weights for partitioning.

Parameters
[in]p8estthe 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 p8est_balance ( p8est_t p8est,
p8est_connect_type_t  btype,
p8est_init_t  init_fn 
)

2:1 balance the size differences of neighboring elements in a forest.

Parameters
[in,out]p8estThe p8est to be worked on.
[in]btypeBalance type (face, edge, or corner/full). Examples: Finite volume or discontinuous Galerkin methods only require face balance. Continuous finite element methods usually require edge balance. Corner balance is almost never required mathematically; it just produces a smoother mesh grading.
[in]init_fnCallback function to initialize the user_data which is already allocated automatically.
unsigned p8est_checksum ( p8est_t p8est)

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 p8est_coarsen ( p8est_t p8est,
int  coarsen_recursive,
p8est_coarsen_t  coarsen_fn,
p8est_init_t  init_fn 
)

Coarsen a forest.

Parameters
[in,out]p8estThe 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.
p8est_t* p8est_copy ( p8est_t input,
int  copy_data 
)

Make a deep copy of a p8est.

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 p8est that does not depend on the input.
void p8est_destroy ( p8est_t p8est)

Destroy a p8est.

Note
The connectivity structure is not destroyed with the p8est.
p8est_t* p8est_load ( const char *  filename,
sc_MPI_Comm  mpicomm,
size_t  data_size,
int  load_data,
void *  user_pointer,
p8est_connectivity_t **  connectivity 
)

Load the complete connectivity/p8est 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 p8est_load_ext() in p8est_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 p8est 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 p8est_memory_used ( p8est_t p8est)

Calculate memory usage of a forest structure.

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

Parameters
[in]p8estForest structure.
Returns
Memory used in bytes.
p8est_t* p8est_new ( sc_MPI_Comm  mpicomm,
p8est_connectivity_t connectivity,
size_t  data_size,
p8est_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 p8est 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 p8est 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 p8est_partition ( p8est_t p8est,
int  allow_for_coarsening,
p8est_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]p8estThe 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 p8est_qcoord_to_vertex ( p8est_connectivity_t connectivity,
p4est_topidx_t  treeid,
p4est_qcoord_t  x,
p4est_qcoord_t  y,
p4est_qcoord_t  z,
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, z.
[in]x,y,zQuadrant coordinates relative to treeid.
[out]vxyzTransformed coordinates in vertex space.
static p8est_quadrant_t* p8est_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 p8est_quadrant_t* p8est_quadrant_array_push ( sc_array_t array)
inlinestatic

Call sc_array_push for a quadrant array.

static p8est_quadrant_t* p8est_quadrant_list_pop ( sc_list_t list)
inlinestatic

Call sc_list pop for a quadrant array.

static p8est_quadrant_t* p8est_quadrant_mempool_alloc ( sc_mempool_t mempool)
inlinestatic

Call sc_mempool_alloc for a mempool creating quadrants.

void p8est_refine ( p8est_t p8est,
int  refine_recursive,
p8est_refine_t  refine_fn,
p8est_init_t  init_fn 
)

Refine a forest.

Parameters
[in,out]p8estThe 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 p8est_refine_ext in p8est_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 p8est_reset_data ( p8est_t p8est,
size_t  data_size,
p8est_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 p8est before init_fn is called the first time.
void p8est_save ( const char *  filename,
p8est_t p8est,
int  save_data 
)

Save the complete connectivity/p8est 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 p8est_save_ext() in p8est_extended.h.

Parameters
[in]filenameName of the file to write.
[in]p8estValid 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 p8est_tree_t* p8est_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].