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

passing quadrants and data to neighboring processes More...

#include <p8est.h>

Go to the source code of this file.

Data Structures

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

Functions

int p8est_ghost_is_valid (p8est_t *p8est, p8est_ghost_t *ghost)
 Examine if a ghost structure is valid as desribed above. More...
 
size_t p8est_ghost_memory_used (p8est_ghost_t *ghost)
 Calculate the memory usage of the ghost layer. More...
 
int p8est_quadrant_find_owner (p8est_t *p8est, p4est_topidx_t treeid, int face, const p8est_quadrant_t *q)
 Gets the processor id of a quadrant's owner. More...
 
p8est_ghost_tp8est_ghost_new (p8est_t *p8est, p8est_connect_type_t btype)
 Builds the ghost layer. More...
 
void p8est_ghost_destroy (p8est_ghost_t *ghost)
 Frees all memory used for the ghost layer. More...
 
ssize_t p8est_ghost_bsearch (p8est_ghost_t *ghost, int which_proc, p4est_topidx_t which_tree, const p8est_quadrant_t *q)
 Conduct binary search for exact match on a range of the ghost layer. More...
 
ssize_t p8est_ghost_tree_contains (p8est_ghost_t *ghost, int which_proc, p4est_topidx_t which_tree, const p8est_quadrant_t *q)
 Conduct binary search for ancestor on range of the ghost layer. More...
 
p4est_locidx_t p8est_face_quadrant_exists (p8est_t *p8est, p8est_ghost_t *ghost, p4est_topidx_t treeid, const p8est_quadrant_t *q, int *face, int *hang, int *owner_rank)
 Checks if quadrant exists in the local forest or the ghost layer. More...
 
int p8est_quadrant_exists (p8est_t *p8est, p8est_ghost_t *ghost, p4est_topidx_t treeid, const p8est_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 p8est_is_balanced (p8est_t *p8est, p8est_connect_type_t btype)
 Check a forest to see if it is balanced. More...
 
unsigned p8est_ghost_checksum (p8est_t *p8est, p8est_ghost_t *ghost)
 Compute the parallel checksum of a ghost layer. More...
 
void p8est_ghost_exchange_data (p8est_t *p4est, p8est_ghost_t *ghost, void *ghost_data)
 Transfer data for local quadrants that are ghosts to other processors. More...
 
void p8est_ghost_exchange_custom (p8est_t *p4est, p8est_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 p8est_ghost_exchange_custom_levels (p8est_t *p8est, p8est_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 p8est_ghost_expand (p8est_t *p8est, p8est_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 p8est_face_quadrant_exists ( p8est_t p8est,
p8est_ghost_t ghost,
p4est_topidx_t  treeid,
const p8est_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 edges or corners.

Parameters
[in]p8estThe 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..23.
[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 p8est_ghost_bsearch ( p8est_ghost_t ghost,
int  which_proc,
p4est_topidx_t  which_tree,
const p8est_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 p8est_ghost_checksum ( p8est_t p8est,
p8est_ghost_t ghost 
)

Compute the parallel checksum of a ghost layer.

Parameters
[in]p8estThe MPI information of this p8est will be used.
[in]ghostA ghost layer obtained from the p8est.
Returns
Parallel checksum on rank 0, 0 otherwise.
void p8est_ghost_destroy ( p8est_ghost_t ghost)

Frees all memory used for the ghost layer.

void p8est_ghost_exchange_custom ( p8est_t p4est,
p8est_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]p8estThe 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.
[in,out]ghost_dataPre-allocated contiguous data for all ghosts in sequence, which must hold at least data_size for each ghost.
void p8est_ghost_exchange_custom_levels ( p8est_t p8est,
p8est_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 p8est_ghost_exchange_data ( p8est_t p4est,
p8est_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 p8est->data_size is 0, or the content of the referenced memory field if p8est->data_size is positive.

Parameters
[in]p8estThe 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 p8est->data_size is 0, must at least hold sizeof (void *) bytes for each, otherwise p8est->data_size each.
void p8est_ghost_expand ( p8est_t p8est,
p8est_ghost_t ghost 
)

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

Parameters
[in]p8estThe forest from which the ghost layer was generated.
[in,out]ghostThe ghost layer to be expanded.
int p8est_ghost_is_valid ( p8est_t p8est,
p8est_ghost_t ghost 
)

Examine if a ghost structure is valid as desribed above.

Test if within a ghost-structure the arrays ghosts and mirrors are 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]p8estthe forest.
[in]ghostGhost layer structure.
Returns
true if ghost is valid
size_t p8est_ghost_memory_used ( p8est_ghost_t ghost)

Calculate the memory usage of the ghost layer.

Parameters
[in]ghostGhost layer structure.
Returns
Memory used in bytes.
p8est_ghost_t* p8est_ghost_new ( p8est_t p8est,
p8est_connect_type_t  btype 
)

Builds the ghost layer.

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

Parameters
[in]p8estThe forest for which the ghost layer will be generated.
[in]btypeWhich ghosts to include (across face, edge, or corner/full).
Returns
A fully initialized ghost layer.
ssize_t p8est_ghost_tree_contains ( p8est_ghost_t ghost,
int  which_proc,
p4est_topidx_t  which_tree,
const p8est_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.
int p8est_is_balanced ( p8est_t p8est,
p8est_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]p8estThe p8est to be tested.
[in]btypeBalance type (face, edge, corner or default, full).
Returns
Returns true if balanced, false otherwise.
int p8est_quadrant_exists ( p8est_t p8est,
p8est_ghost_t ghost,
p4est_topidx_t  treeid,
const p8est_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 p8est_quadrant_find_owner ( p8est_t p8est,
p4est_topidx_t  treeid,
int  face,
const p8est_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]p8estThe 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.