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

passing quadrants and data to neighboring processes More...

#include <p4est.h>

Go to the source code of this file.

Data Structures

struct  p4est_ghost_t
 quadrants that neighbor the local domain More...
 

Functions

int p4est_ghost_is_valid (p4est_t *p4est, p4est_ghost_t *ghost)
 Examine if a ghost structure is valid. More...
 
size_t p4est_ghost_memory_used (p4est_ghost_t *ghost)
 Calculate the memory usage of the ghost layer. More...
 
int p4est_quadrant_find_owner (p4est_t *p4est, p4est_topidx_t treeid, int face, const p4est_quadrant_t *q)
 Gets the processor id of a quadrant's owner. More...
 
p4est_ghost_tp4est_ghost_new (p4est_t *p4est, p4est_connect_type_t btype)
 Builds the ghost layer. More...
 
void p4est_ghost_destroy (p4est_ghost_t *ghost)
 Frees all memory used for the ghost layer. More...
 
ssize_t p4est_ghost_bsearch (p4est_ghost_t *ghost, int which_proc, p4est_topidx_t which_tree, const p4est_quadrant_t *q)
 Conduct binary search for exact match on a range of the ghost layer. More...
 
ssize_t p4est_ghost_contains (p4est_ghost_t *ghost, int which_proc, p4est_topidx_t which_tree, const p4est_quadrant_t *q)
 Conduct binary search for ancestor on range of the ghost layer. More...
 
p4est_locidx_t p4est_face_quadrant_exists (p4est_t *p4est, p4est_ghost_t *ghost, p4est_topidx_t treeid, const p4est_quadrant_t *q, int *face, int *hang, int *owner_rank)
 Checks if quadrant exists in the local forest or the ghost layer. More...
 
int p4est_quadrant_exists (p4est_t *p4est, p4est_ghost_t *ghost, p4est_topidx_t treeid, const p4est_quadrant_t *q, sc_array_t *exists_arr, sc_array_t *rproc_arr, sc_array_t *rquad_arr)
 Checks if quadrant exists in the local forest or the ghost layer. More...
 
int p4est_is_balanced (p4est_t *p4est, p4est_connect_type_t btype)
 Check a forest to see if it is balanced. More...
 
unsigned p4est_ghost_checksum (p4est_t *p4est, p4est_ghost_t *ghost)
 Compute the parallel checksum of a ghost layer. More...
 
void p4est_ghost_exchange_data (p4est_t *p4est, p4est_ghost_t *ghost, void *ghost_data)
 Transfer data for local quadrants that are ghosts to other processors. More...
 
void p4est_ghost_exchange_custom (p4est_t *p4est, p4est_ghost_t *ghost, size_t data_size, void **mirror_data, void *ghost_data)
 Transfer data for local quadrants that are ghosts to other processors. More...
 
void p4est_ghost_exchange_custom_levels (p4est_t *p4est, p4est_ghost_t *ghost, int minlevel, int maxlevel, size_t data_size, void **mirror_data, void *ghost_data)
 Transfer data for local quadrants that are ghosts to other processors. More...
 
void p4est_ghost_expand (p4est_t *p4est, p4est_ghost_t *ghost)
 Expand the size of the ghost layer and mirrors by one additional layer of adjacency. More...
 

Detailed Description

passing quadrants and data to neighboring processes

Function Documentation

p4est_locidx_t p4est_face_quadrant_exists ( p4est_t p4est,
p4est_ghost_t ghost,
p4est_topidx_t  treeid,
const p4est_quadrant_t q,
int *  face,
int *  hang,
int *  owner_rank 
)

Checks if quadrant exists in the local forest or the ghost layer.

For quadrants across tree boundaries it checks if the quadrant exists across any face, but not across corners.

Parameters
[in]p4estThe forest in which to search for q.
[in]ghostThe ghost layer in which to search for q.
[in]treeidThe tree to which q belongs.
[in]qThe quadrant that is being searched for.
[in,out]faceOn input, face id across which q was created. On output, the neighbor's face number augmented by orientation, so face is in 0..7.
[in,out]hangIf not NULL, signals that q is bigger than the quadrant it came from. The child id of that originating quadrant is passed into hang. On output, hang holds the hanging face number of q that is in contact with its originator.
[out]owner_rankFilled with the rank of the owner if it is found and undefined otherwise.
Returns
Returns the local number of q if the quadrant exists in the local forest or in the ghost_layer. Otherwise, returns -2 for a domain boundary and -1 if not found.
ssize_t p4est_ghost_bsearch ( p4est_ghost_t ghost,
int  which_proc,
p4est_topidx_t  which_tree,
const p4est_quadrant_t q 
)

Conduct binary search for exact match on a range of the ghost layer.

Parameters
[in]ghostThe ghost layer.
[in]which_procThe owner of the searched quadrant. Can be -1.
[in]which_treeThe tree of the searched quadrant. Can be -1.
[in]qValid quadrant is searched in the ghost layer.
Returns
Offset in the ghost layer, or -1 if not found.
unsigned p4est_ghost_checksum ( p4est_t p4est,
p4est_ghost_t ghost 
)

Compute the parallel checksum of a ghost layer.

Parameters
[in]p4estThe MPI information of this p4est will be used.
[in]ghostA ghost layer obtained from the p4est.
Returns
Parallel checksum on rank 0, 0 otherwise.
ssize_t p4est_ghost_contains ( p4est_ghost_t ghost,
int  which_proc,
p4est_topidx_t  which_tree,
const p4est_quadrant_t q 
)

Conduct binary search for ancestor on range of the ghost layer.

Parameters
[in]ghostThe ghost layer.
[in]which_procThe owner of the searched quadrant. Can be -1.
[in]which_treeThe tree of the searched quadrant. Can be -1.
[in]qValid quadrant's ancestor is searched.
Returns
Offset in the ghost layer, or -1 if not found.
void p4est_ghost_destroy ( p4est_ghost_t ghost)

Frees all memory used for the ghost layer.

void p4est_ghost_exchange_custom ( p4est_t p4est,
p4est_ghost_t ghost,
size_t  data_size,
void **  mirror_data,
void *  ghost_data 
)

Transfer data for local quadrants that are ghosts to other processors.

The data size is the same for all quadrants and can be chosen arbitrarily.

Parameters
[in]p4estThe forest used for reference.
[in]ghostThe ghost layer used for reference.
[in]data_sizeThe data size to transfer per quadrant.
[in]mirror_dataOne data pointer per mirror quadrant as input.
[in,out]ghost_dataPre-allocated contiguous data for all ghosts in sequence, which must hold at least data_size for each ghost.
void p4est_ghost_exchange_custom_levels ( p4est_t p4est,
p4est_ghost_t ghost,
int  minlevel,
int  maxlevel,
size_t  data_size,
void **  mirror_data,
void *  ghost_data 
)

Transfer data for local quadrants that are ghosts to other processors.

The data size is the same for all quadrants and can be chosen arbitrarily. This function restricts the transfer to a range of refinement levels. The memory for quadrants outside the level range is not dereferenced.

Parameters
[in]p4estThe forest used for reference.
[in]ghostThe ghost layer used for reference.
[in]minlevelLevel of the largest quads to be exchanged. Use <= 0 for no restriction.
[in]maxlevelLevel of the smallest quads to be exchanged. Use >= P4EST_QMAXLEVEL for no restriction.
[in]data_sizeThe data size to transfer per quadrant.
[in]mirror_dataOne data pointer per mirror quadrant as input.
[in,out]ghost_dataPre-allocated contiguous data for all ghosts in sequence, which must hold at least data_size for each ghost.
void p4est_ghost_exchange_data ( p4est_t p4est,
p4est_ghost_t ghost,
void *  ghost_data 
)

Transfer data for local quadrants that are ghosts to other processors.

Send the data stored in the quadrant's user_data. This is either the pointer variable itself if p4est->data_size is 0, or the content of the referenced memory field if p4est->data_size is positive.

Parameters
[in]p4estThe forest used for reference.
[in]ghostThe ghost layer used for reference.
[in,out]ghost_dataPre-allocated contiguous data for all ghost quadrants in sequence. If p4est->data_size is 0, must at least hold sizeof (void *) bytes for each, otherwise p4est->data_size each.
void p4est_ghost_expand ( p4est_t p4est,
p4est_ghost_t ghost 
)

Expand the size of the ghost layer and mirrors by one additional layer of adjacency.

Parameters
[in]p4estThe forest from which the ghost layer was generated.
[in,out]ghostThe ghost layer to be expanded.
int p4est_ghost_is_valid ( p4est_t p4est,
p4est_ghost_t ghost 
)

Examine if a ghost structure is valid.

Test if within a ghost-structure the array ghosts is in p4est_quadrant_compare_piggy order. Test if local_num in piggy3 data member of the quadrants in ghosts and mirrors are in ascending order (ascending within each rank for ghost).

Test if the p4est_locidx_t arrays are in ascending order (for mirror_proc_mirrors ascending within each rank)

Parameters
[in]p4estthe forest.
[in]ghostGhost layer structure.
Returns
true if ghost is valid
size_t p4est_ghost_memory_used ( p4est_ghost_t ghost)

Calculate the memory usage of the ghost layer.

Parameters
[in]ghostGhost layer structure.
Returns
Memory used in bytes.
p4est_ghost_t* p4est_ghost_new ( p4est_t p4est,
p4est_connect_type_t  btype 
)

Builds the ghost layer.

This will gather the quadrants from each neighboring proc to build one layer of face and corner based ghost elements around the ones they own.

Parameters
[in]p4estThe forest for which the ghost layer will be generated.
[in]btypeWhich ghosts to include (across face, corner or full).
Returns
A fully initialized ghost layer.
int p4est_is_balanced ( p4est_t p4est,
p4est_connect_type_t  btype 
)

Check a forest to see if it is balanced.

This function builds the ghost layer and discards it when done.

Parameters
[in]p4estThe p4est to be tested.
[in]btypeBalance type (face, corner or default, full).
Returns
Returns true if balanced, false otherwise.
int p4est_quadrant_exists ( p4est_t p4est,
p4est_ghost_t ghost,
p4est_topidx_t  treeid,
const p4est_quadrant_t q,
sc_array_t exists_arr,
sc_array_t rproc_arr,
sc_array_t rquad_arr 
)

Checks if quadrant exists in the local forest or the ghost layer.

For quadrants across tree corners it checks if the quadrant exists in any of the corner neighbors, thus it can execute multiple queries.

Parameters
[in]p4estThe forest in which to search for q
[in]ghostThe ghost layer in which to search for q
[in]treeidThe tree to which q belongs (can be extended).
[in]qThe quadrant that is being searched for.
[in,out]exists_arrMust exist and be of of elem_size = sizeof (int) for inter-tree corner cases. Is resized by this function to one entry for each corner search and set to true/false depending on its existence in the local forest or ghost_layer.
[in,out]rproc_arrIf not NULL is filled with one rank per query.
[in,out]rquad_arrIf not NULL is filled with one quadrant per query. Its piggy3 member is defined as well.
Returns
true if the quadrant exists in the local forest or in the ghost_layer, and false if doesn't exist in either.
int p4est_quadrant_find_owner ( p4est_t p4est,
p4est_topidx_t  treeid,
int  face,
const p4est_quadrant_t q 
)

Gets the processor id of a quadrant's owner.

The quadrant can lie outside of a tree across faces (and only faces).

Parameters
[in]p4estThe forest in which to search for a quadrant.
[in]treeidThe tree to which the quadrant belongs.
[in]faceSupply a face direction if known, or -1 otherwise.
[in]qThe quadrant that is being searched for.
Returns
Processor id of the owner or -1 if the quadrant lies outside of the mesh.
Warning
Does not work for tree edge or corner neighbors.