passing quadrants and data to neighboring processes More...

#include <p8est.h>

Include dependency graph for p8est_ghost.h:

This graph shows which files directly or indirectly include this file:

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

struct	p8est_ghost_exchange
	Transient storage for asynchronous ghost exchange. More...

Typedefs
typedef struct p8est_ghost_exchange	p8est_ghost_exchange_t
	Transient storage for asynchronous ghost exchange.

Functions
int	p8est_ghost_is_valid (p8est_t p8est, p8est_ghost_t ghost)
	Examine if a ghost structure is valid as described 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_t *	p8est_ghost_new (p8est_t *p8est, p8est_connect_type_t btype)
	Builds the ghost layer. More...

p8est_ghost_t *	p8est_ghost_new_local (p8est_t *p8est, p8est_connect_type_t ctype)
	Generate an empty ghost layer. More...

void	p8est_ghost_destroy (p8est_ghost_t *ghost)
	Frees all memory used for the ghost layer.

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 p8est, p8est_ghost_t ghost, void *ghost_data)
	Transfer data for local quadrants that are ghosts to other processors. More...

p8est_ghost_exchange_t *	p8est_ghost_exchange_data_begin (p8est_t p8est, p8est_ghost_t ghost, void *ghost_data)
	Begin an asynchronous ghost data exchange by posting messages. More...

void	p8est_ghost_exchange_data_end (p8est_ghost_exchange_t *exc)
	Complete an asynchronous ghost data exchange. More...

void	p8est_ghost_exchange_custom (p8est_t p8est, 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...

p8est_ghost_exchange_t *	p8est_ghost_exchange_custom_begin (p8est_t p8est, p8est_ghost_t ghost, size_t data_size, void *mirror_data, void ghost_data)
	Begin an asynchronous ghost data exchange by posting messages. More...

void	p8est_ghost_exchange_custom_end (p8est_ghost_exchange_t *exc)
	Complete an asynchronous ghost data exchange. 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...

p8est_ghost_exchange_t *	p8est_ghost_exchange_custom_levels_begin (p8est_t p8est, p8est_ghost_t ghost, int minlevel, int maxlevel, size_t data_size, void *mirror_data, void ghost_data)
	Begin an asynchronous ghost data exchange by posting messages. More...

void	p8est_ghost_exchange_custom_levels_end (p8est_ghost_exchange_t *exc)
	Complete an asynchronous ghost data exchange. 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

◆ p8est_face_quadrant_exists()

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]	p8est	The forest in which to search for q.
[in]	ghost	The ghost layer in which to search for q.
[in]	treeid	The tree to which q belongs.
[in]	q	The quadrant that is being searched for.
[in,out]	face	On 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]	hang	If 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_rank	Filled 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.

◆ p8est_ghost_bsearch()

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]	ghost	The ghost layer.
[in]	which_proc	The owner of the searched quadrant. Can be -1.
[in]	which_tree	The tree of the searched quadrant. Can be -1.
[in]	q	Valid quadrant is searched in the ghost layer.

Returns: Offset in the ghost layer, or -1 if not found.

◆ p8est_ghost_checksum()

unsigned p8est_ghost_checksum	(	p8est_t *	p8est,
		p8est_ghost_t *	ghost
	)

Compute the parallel checksum of a ghost layer.

Parameters

[in]	p8est	The MPI information of this p8est will be used.
[in]	ghost	A ghost layer obtained from the p8est.

Returns: Parallel checksum on rank 0, 0 otherwise.

◆ p8est_ghost_exchange_custom()

void p8est_ghost_exchange_custom	(	p8est_t *	p8est,
		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]	p8est	The forest used for reference.
[in]	ghost	The ghost layer used for reference.
[in]	data_size	The data size to transfer per quadrant.
[in]	mirror_data	One data pointer per mirror quadrant.
[in,out]	ghost_data	Pre-allocated contiguous data for all ghosts in sequence, which must hold at least `data_size` for each ghost.

◆ p8est_ghost_exchange_custom_begin()

p8est_ghost_exchange_t * p8est_ghost_exchange_custom_begin	(	p8est_t *	p8est,
		p8est_ghost_t *	ghost,
		size_t	data_size,
		void **	mirror_data,
		void *	ghost_data
	)

Begin an asynchronous ghost data exchange by posting messages.

The arguments are identical to p8est_ghost_exchange_custom. The return type is always non-NULL and must be passed to p8est_ghost_exchange_custom_end to complete the exchange. The ghost data must not be accessed before completion. The mirror data can be safely discarded right after this function returns since it is copied into internal send buffers.

Parameters

[in]	mirror_data	Not required to stay alive any longer.
[in,out]	ghost_data	Must stay alive into the completion call.

Returns: Transient storage for messages in progress.

◆ p8est_ghost_exchange_custom_end()

void p8est_ghost_exchange_custom_end ( p8est_ghost_exchange_t * exc )

Complete an asynchronous ghost data exchange.

This function waits for all pending MPI communications.

Parameters

[in,out] Data created ONLY by p8est_ghost_exchange_custom_begin. It is deallocated before this function returns.

◆ p8est_ghost_exchange_custom_levels()

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]	p8est	The forest used for reference.
[in]	ghost	The ghost layer used for reference.
[in]	minlevel	Level of the largest quads to be exchanged. Use <= 0 for no restriction.
[in]	maxlevel	Level of the smallest quads to be exchanged. Use >= P8EST_QMAXLEVEL for no restriction.
[in]	data_size	The data size to transfer per quadrant.
[in]	mirror_data	One data pointer per mirror quadrant as input.
[in,out]	ghost_data	Pre-allocated contiguous data for all ghosts in sequence, which must hold at least `data_size` for each ghost.

◆ p8est_ghost_exchange_custom_levels_begin()

p8est_ghost_exchange_t * p8est_ghost_exchange_custom_levels_begin	(	p8est_t *	p8est,
		p8est_ghost_t *	ghost,
		int	minlevel,
		int	maxlevel,
		size_t	data_size,
		void **	mirror_data,
		void *	ghost_data
	)

Begin an asynchronous ghost data exchange by posting messages.

The arguments are identical to p8est_ghost_exchange_custom_levels. The return type is always non-NULL and must be passed to p8est_ghost_exchange_custom_levels_end to complete the exchange. The ghost data must not be accessed before completion. The mirror data can be safely discarded right after this function returns since it is copied into internal send buffers.

Parameters

[in]	mirror_data	Not required to stay alive any longer.
[in,out]	ghost_data	Must stay alive into the completion call.

Returns: Transient storage for messages in progress.

◆ p8est_ghost_exchange_custom_levels_end()

void p8est_ghost_exchange_custom_levels_end ( p8est_ghost_exchange_t * exc )

Complete an asynchronous ghost data exchange.

This function waits for all pending MPI communications.

Parameters

[in,out] exc created ONLY by p8est_ghost_exchange_custom_levels_begin. It is deallocated before this function returns.

◆ p8est_ghost_exchange_data()

void p8est_ghost_exchange_data	(	p8est_t *	p8est,
		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]	p8est	The forest used for reference.
[in]	ghost	The ghost layer used for reference.
[in,out]	ghost_data	Pre-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.

◆ p8est_ghost_exchange_data_begin()

p8est_ghost_exchange_t * p8est_ghost_exchange_data_begin	(	p8est_t *	p8est,
		p8est_ghost_t *	ghost,
		void *	ghost_data
	)

Begin an asynchronous ghost data exchange by posting messages.

The arguments are identical to p8est_ghost_exchange_data. The return type is always non-NULL and must be passed to p8est_ghost_exchange_data_end to complete the exchange. The ghost data must not be accessed before completion.

Parameters

[in,out] ghost_data Must stay alive into the completion call.

Returns: Transient storage for messages in progress.

◆ p8est_ghost_exchange_data_end()

void p8est_ghost_exchange_data_end ( p8est_ghost_exchange_t * exc )

Complete an asynchronous ghost data exchange.

This function waits for all pending MPI communications.

Parameters

[in,out] exc Created ONLY by p8est_ghost_exchange_data_begin. It is deallocated before this function returns.

◆ p8est_ghost_expand()

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]	p8est	The forest from which the ghost layer was generated.
[in,out]	ghost	The ghost layer to be expanded.

◆ p8est_ghost_is_valid()

int p8est_ghost_is_valid	(	p8est_t *	p8est,
		p8est_ghost_t *	ghost
	)

Examine if a ghost structure is valid as described above.

Test if within a ghost-structure the arrays ghosts and mirrors are in p8est_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]	p8est	the forest.
[in]	ghost	Ghost layer structure.

Returns: true if ghost is valid

◆ p8est_ghost_memory_used()

size_t p8est_ghost_memory_used ( p8est_ghost_t * ghost )

Calculate the memory usage of the ghost layer.

Parameters

[in] ghost Ghost layer structure.

Returns: Memory used in bytes.

◆ p8est_ghost_new()

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]	p8est	The forest for which the ghost layer will be generated.
[in]	btype	Which ghosts to include (across face, edge, or corner/full).

Returns: A fully initialized ghost layer.

◆ p8est_ghost_new_local()

p8est_ghost_t * p8est_ghost_new_local	(	p8est_t *	p8est,
		p8est_connect_type_t	ctype
	)

Generate an empty ghost layer.

This ghost layer pretends that there are no parallel neighbor elements. It is useful if general algorithms should be run with local data only.

Parameters

[in]	p8est	Valid forest.
[in]	ctype	Ghosts to include (none, across face, face/corner). This variable must be valid but has no effect.

Returns: Valid ghost layer of zero ghost elements.

◆ p8est_ghost_tree_contains()

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]	ghost	The ghost layer.
[in]	which_proc	The owner of the searched quadrant. Can be -1.
[in]	which_tree	The tree of the searched quadrant. Can be -1.
[in]	q	Valid quadrant's ancestor is searched.

Returns: Offset in the ghost layer, or -1 if not found.

◆ p8est_is_balanced()

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]	p8est	The p8est to be tested.
[in]	btype	Balance type (face, edge, corner or default, full).

Returns: Returns true if balanced, false otherwise.

◆ p8est_quadrant_exists()

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]	p8est	The forest in which to search for q
[in]	ghost	The ghost layer in which to search for q
[in]	treeid	The tree to which q belongs (can be extended).
[in]	q	The quadrant that is being searched for.
[in,out]	exists_arr	Must 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_arr	If not NULL is filled with one rank per query.
[in,out]	rquad_arr	If 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.

◆ p8est_quadrant_find_owner()

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]	p8est	The forest in which to search for a quadrant.
[in]	treeid	The tree to which the quadrant belongs.
[in]	face	Supply a face direction if known, or -1 otherwise.
[in]	q	The 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.

Data Structures

Typedefs

Functions

Detailed Description

Function Documentation

◆ p8est_face_quadrant_exists()

◆ p8est_ghost_bsearch()

◆ p8est_ghost_checksum()

◆ p8est_ghost_exchange_custom()

◆ p8est_ghost_exchange_custom_begin()

◆ p8est_ghost_exchange_custom_end()

◆ p8est_ghost_exchange_custom_levels()

◆ p8est_ghost_exchange_custom_levels_begin()

◆ p8est_ghost_exchange_custom_levels_end()

◆ p8est_ghost_exchange_data()

◆ p8est_ghost_exchange_data_begin()

◆ p8est_ghost_exchange_data_end()

◆ p8est_ghost_expand()

◆ p8est_ghost_is_valid()

◆ p8est_ghost_memory_used()

◆ p8est_ghost_new()

◆ p8est_ghost_new_local()

◆ p8est_ghost_tree_contains()

◆ p8est_is_balanced()

◆ p8est_quadrant_exists()

◆ p8est_quadrant_find_owner()