The logic in p8est_wrap encapsulates core p4est data structures and provides functions that clarify the mark-adapt-partition cycle. More...

#include <p8est_extended.h>
#include <sc_refcount.h>

Include dependency graph for p8est_wrap.h:

Go to the source code of this file.

Data Structures
struct	p8est_wrap_params_t
	This structure contains the different parameters of wrap creation. More...

struct	p8est_wrap

struct	p8est_wrap_leaf

Macros
#define	P8EST_LEAF_IS_FIRST_IN_TREE(wleaf) ((wleaf)->which_quad == 0)
	Determine whether we have just entered a different tree.

Typedefs
typedef enum p8est_wrap_flags	p8est_wrap_flags_t

typedef struct p8est_wrap	p8est_wrap_t

typedef struct p8est_wrap_leaf	p8est_wrap_leaf_t

Enumerations
enum	p8est_wrap_flags { P8EST_WRAP_NONE = 0 , P8EST_WRAP_REFINE = 0x01 , P8EST_WRAP_COARSEN = 0x02 }

Functions
void	p8est_wrap_params_init (p8est_wrap_params_t *params)
	Initialize a default p8est_wrap_params_t structure. More...

p8est_wrap_t *	p8est_wrap_new_conn (sc_MPI_Comm mpicomm, p8est_connectivity_t *conn, int initial_level)
	Create a p8est wrapper from a given connectivity structure. More...

p8est_wrap_t *	p8est_wrap_new_p8est (p8est_t p8est, int hollow, p8est_connect_type_t btype, p8est_replace_t replace_fn, void user_pointer)
	Create a wrapper for a given p8est structure. More...

p8est_wrap_t *	p8est_wrap_new_p8est_params (p8est_t p8est, p8est_wrap_params_t params)
	Create a wrapper for a given p8est structure. More...

p8est_wrap_t *	p8est_wrap_new_ext (sc_MPI_Comm mpicomm, p8est_connectivity_t conn, int initial_level, int hollow, p8est_connect_type_t btype, p8est_replace_t replace_fn, void user_pointer)
	Create a p8est wrapper from a given connectivity structure. More...

p8est_wrap_t *	p8est_wrap_new_params (sc_MPI_Comm mpicomm, p8est_connectivity_t conn, int initial_level, p8est_wrap_params_t params)
	Create a p8est wrapper from a given connectivity structure. More...

p8est_wrap_t *	p8est_wrap_new_copy (p8est_wrap_t source, size_t data_size, p8est_replace_t replace_fn, void user_pointer)
	Create a p8est wrapper from an existing one. More...

p8est_wrap_t *	p8est_wrap_new_unitcube (sc_MPI_Comm mpicomm, int initial_level)
	Create p8est and auxiliary data structures. More...

p8est_wrap_t *	p8est_wrap_new_rotwrap (sc_MPI_Comm mpicomm, int initial_level)

p8est_wrap_t *	p8est_wrap_new_brick (sc_MPI_Comm mpicomm, int bx, int by, int bz, int px, int py, int pz, int initial_level)

p8est_wrap_t *	p8est_wrap_new_world (int initial_level)
	Passes sc_MPI_COMM_WORLD to p8est_wrap_new_unitcube.

void	p8est_wrap_destroy (p8est_wrap_t *pp)

void	p8est_wrap_set_hollow (p8est_wrap_t *pp, int hollow)
	Change hollow status of the wrap. More...

void	p8est_wrap_set_coarsen_delay (p8est_wrap_t *pp, int coarsen_delay, int coarsen_affect)
	Set a parameter that delays coarsening after adaptation. More...

void	p8est_wrap_set_partitioning (p8est_wrap_t *pp, int partition_for_coarsening)
	Set a parameter that ensures future partitions allow one level of coarsening. More...

p8est_ghost_t *	p8est_wrap_get_ghost (p8est_wrap_t *pp)
	Return the appropriate ghost layer. More...

p8est_mesh_t *	p8est_wrap_get_mesh (p8est_wrap_t *pp)
	Return the appropriate mesh structure. More...

void	p8est_wrap_mark_refine (p8est_wrap_t *pp, p4est_topidx_t which_tree, p4est_locidx_t which_quad)
	Mark a local element for refinement. More...

void	p8est_wrap_mark_coarsen (p8est_wrap_t *pp, p4est_topidx_t which_tree, p4est_locidx_t which_quad)
	Mark a local element for coarsening. More...

int	p8est_wrap_adapt (p8est_wrap_t *pp)
	Call p8est_refine, coarsen, and balance to update pp->p8est. More...

int	p8est_wrap_partition (p8est_wrap_t pp, int weight_exponent, p4est_locidx_t unchanged_first, p4est_locidx_t unchanged_length, p4est_locidx_t unchanged_old_first)
	Call p8est_partition for equal leaf distribution. More...

void	p8est_wrap_complete (p8est_wrap_t *pp)
	Free memory for the intermediate mesh. More...

p8est_wrap_leaf_t *	p8est_wrap_leaf_first (p8est_wrap_t *pp, int track_mirrors)

p8est_wrap_leaf_t *	p8est_wrap_leaf_next (p8est_wrap_leaf_t *leaf)

Detailed Description

The logic in p8est_wrap encapsulates core p4est data structures and provides functions that clarify the mark-adapt-partition cycle.

There is also an element iterator that can replace the nested loops over trees and tree quadrants, respectively, which can help make application code cleaner.

Function Documentation

◆ p8est_wrap_adapt()

int p8est_wrap_adapt ( p8est_wrap_t * pp )

Call p8est_refine, coarsen, and balance to update pp->p8est.

Checks pp->flags as per-quadrant input against p8est_wrap_flags_t. The pp->flags array is updated along with p8est and reset to zeros. Creates ghost_aux and mesh_aux to represent the intermediate mesh. If zlib is available, the routine checks whether coarsening and balancing the p8est canceled out and skips computing ghost_aux and mesh_aux when possible.

Parameters

[in,out] pp The p8est wrapper to work with, must not be hollow.

Returns: boolean whether p8est has changed. If true, partition must be called. If false, partition must not be called, and complete must not be called either.

◆ p8est_wrap_complete()

void p8est_wrap_complete ( p8est_wrap_t * pp )

Free memory for the intermediate mesh.

Sets mesh_aux and ghost_aux to NULL. This function must be used if both refinement and partition effect changes. After this call, we are ready for another mark-refine-partition cycle.

Parameters

[in,out] pp The p8est wrapper to work with, must not be hollow.

◆ p8est_wrap_get_ghost()

p8est_ghost_t * p8est_wrap_get_ghost ( p8est_wrap_t * pp )

Return the appropriate ghost layer.

This function is necessary since two versions may exist simultaneously after refinement and before partition/complete.

Parameters

[in,out] pp The p8est wrapper to work with, must not be hollow.

◆ p8est_wrap_get_mesh()

p8est_mesh_t * p8est_wrap_get_mesh ( p8est_wrap_t * pp )

Return the appropriate mesh structure.

This function is necessary since two versions may exist simultaneously after refinement and before partition/complete.

Parameters

[in,out] pp The p8est wrapper to work with, must not be hollow.

◆ p8est_wrap_mark_coarsen()

void p8est_wrap_mark_coarsen	(	p8est_wrap_t *	pp,
		p4est_topidx_t	which_tree,
		p4est_locidx_t	which_quad
	)

Mark a local element for coarsening.

This will cancel any refinement mark set previously for this element.

Parameters

[in,out]	pp	The p8est wrapper to work with, must not be hollow.
[in]	which_tree	The number of the tree this element lives in.
[in]	which_quad	The number of this element relative to its tree.

◆ p8est_wrap_mark_refine()

void p8est_wrap_mark_refine	(	p8est_wrap_t *	pp,
		p4est_topidx_t	which_tree,
		p4est_locidx_t	which_quad
	)

Mark a local element for refinement.

This will cancel any coarsening mark set previously for this element.

Parameters

[in,out]	pp	The p8est wrapper to work with, must not be hollow.
[in]	which_tree	The number of the tree this element lives in.
[in]	which_quad	The number of this element relative to its tree.

◆ p8est_wrap_new_conn()

p8est_wrap_t * p8est_wrap_new_conn	(	sc_MPI_Comm	mpicomm,
		p8est_connectivity_t *	conn,
		int	initial_level
	)

Create a p8est wrapper from a given connectivity structure.

The ghost and mesh members are initialized as well as the flags. The btype is set to P8EST_CONNECT_FULL. This function sets a subset of the wrap creation parameters. For full control use p8est_wrap_new_params.

Parameters

[in]	mpicomm	We expect sc_MPI_Init to be called already.
[in]	conn	Connectivity structure. Wrap takes ownership.
[in]	initial_level	Initial level of uniform refinement.

Returns: A fully initialized p8est_wrap structure.

◆ p8est_wrap_new_copy()

p8est_wrap_t * p8est_wrap_new_copy	(	p8est_wrap_t *	source,
		size_t	data_size,
		p8est_replace_t	replace_fn,
		void *	user_pointer
	)

Create a p8est wrapper from an existing one.

Note: This wrapper must be destroyed before the original one. We set it to hollow and copy the original p8est data structure.

Parameters

[in,out]	source	We access the source for debugging purposes.
[in]	data_size	The data size installed in the copied forest.
[in]	replace_fn	Callback to replace quadrants during refinement, coarsening or balancing in p8est_wrap_adapt. May be NULL.
[in]	user_pointer	Set the user pointer in p8est_wrap_t. Subsequently, we will never access it.

Returns: A fully initialized p8est_wrap structure.

◆ p8est_wrap_new_ext()

p8est_wrap_t * p8est_wrap_new_ext	(	sc_MPI_Comm	mpicomm,
		p8est_connectivity_t *	conn,
		int	initial_level,
		int	hollow,
		p8est_connect_type_t	btype,
		p8est_replace_t	replace_fn,
		void *	user_pointer
	)

Create a p8est wrapper from a given connectivity structure.

Like p8est_wrap_new_conn, but with extra parameters hollow and btype. This function sets a subset of the wrap creation parameters. For full control use p8est_wrap_new_params.

Parameters

[in]	mpicomm	We expect sc_MPI_Init to be called already.
[in]	conn	Connectivity structure. Wrap takes ownership.
[in]	initial_level	Initial level of uniform refinement. No effect if less/equal to zero.
[in]	hollow	Do not allocate flags, ghost, and mesh members.
[in]	btype	The neighborhood used for balance, ghost, mesh.
[in]	replace_fn	Callback to replace quadrants during refinement, coarsening or balancing in p8est_wrap_adapt. May be NULL.
[in]	user_pointer	Set the user pointer in p8est_wrap_t. Subsequently, we will never access it.

Returns: A fully initialized p8est_wrap structure.

◆ p8est_wrap_new_p8est()

p8est_wrap_t * p8est_wrap_new_p8est	(	p8est_t *	p8est,
		int	hollow,
		p8est_connect_type_t	btype,
		p8est_replace_t	replace_fn,
		void *	user_pointer
	)

Create a wrapper for a given p8est structure.

Parameters

[in,out]	p8est	Valid p8est object that we will own. We take ownership of its connectivity too. Its user pointer must be NULL and will be changed. Its data size will be set to 0 and the quadrant data will be freed.
[in]	hollow	Do not allocate flags, ghost, and mesh members.
[in]	btype	The neighborhood used for balance, ghost, mesh.
[in]	replace_fn	Callback to replace quadrants during refinement, coarsening or balancing in p8est_wrap_adapt. May be NULL.
[in]	user_pointer	Set the user pointer in p8est_wrap_t. Subsequently, we will never access it.

Returns: A fully initialized p8est_wrap structure.

◆ p8est_wrap_new_p8est_params()

p8est_wrap_t * p8est_wrap_new_p8est_params	(	p8est_t *	p8est,
		p8est_wrap_params_t *	params
	)

Create a wrapper for a given p8est structure.

Like p8est_wrap_new_p8est, but with params to completely control the wrap creation process.

Parameters

[in,out]	p8est	Valid p8est object that we will own. We take ownership of its connectivity too. Its user pointer must be NULL and will be changed. Its data size will be set to 0 and the quadrant data will be freed.
[in]	params	The wrap creation parameters. If NULL, the function defaults to the parameters of p8est_wrap_params_init.

Returns: A fully initialized p4est_wrap structure.

◆ p8est_wrap_new_params()

p8est_wrap_t * p8est_wrap_new_params	(	sc_MPI_Comm	mpicomm,
		p8est_connectivity_t *	conn,
		int	initial_level,
		p8est_wrap_params_t *	params
	)

Create a p8est wrapper from a given connectivity structure.

Like p8est_wrap_new_conn, but with params to completely control the wrap creation process.

Parameters

[in]	mpicomm	We expect sc_MPI_Init to be called already.
[in]	conn	Connectivity structure. Wrap takes ownership.
[in]	initial_level	Initial level of uniform refinement. No effect if less/equal to zero.
[in]	params	The wrap creation parameters. If NULL, the function defaults to the parameters of p8est_wrap_params_init.

Returns: A fully initialized p8est_wrap structure.

◆ p8est_wrap_new_unitcube()

p8est_wrap_t * p8est_wrap_new_unitcube	(	sc_MPI_Comm	mpicomm,
		int	initial_level
	)

Create p8est and auxiliary data structures.

Expects sc_MPI_Init to be called beforehand.

◆ p8est_wrap_params_init()

void p8est_wrap_params_init ( p8est_wrap_params_t * params )

Initialize a default p8est_wrap_params_t structure.

The parameters are set to create the most basic, hollow wrap structure.

◆ p8est_wrap_partition()

int p8est_wrap_partition	(	p8est_wrap_t *	pp,
		int	weight_exponent,
		p4est_locidx_t *	unchanged_first,
		p4est_locidx_t *	unchanged_length,
		p4est_locidx_t *	unchanged_old_first
	)

Call p8est_partition for equal leaf distribution.

Frees the old ghost and mesh first and updates pp->flags along with p8est. Creates ghost and mesh to represent the new mesh.

Parameters

[in,out]	pp	The p8est wrapper to work with, must not be hollow.
[in]	weight_exponent	Integer weight assigned to each leaf according to 2 ** (level * exponent). Passing 0 assigns equal weight to all leaves. Passing 1 increases the leaf weight by a factor of two for each level increase. CURRENTLY ONLY 0 AND 1 ARE LEGAL VALUES.
[out]	unchanged_first	If not NULL, is assigned the processor-local index of the first local quadrant that has stayed on this processor. If no quadrant has stayed, the value is set to zero. This number is in reference to the new (output) partition.
[out]	unchanged_length	If not NULL, is assigned the number of quadrants that have stayed on this processor. If no quadrant has stayed, the value is set to zero.
[out]	unchanged_old_first	If not NULL, is assigned the processor-local index of the first local quadrant that has stayed with reference to the old (input) partition. If no quadrant has stayed, the value is set to zero.

Returns: boolean whether p8est has changed. If true, complete must be called. If false, complete must not be called.

◆ p8est_wrap_set_coarsen_delay()

void p8est_wrap_set_coarsen_delay	(	p8est_wrap_t *	pp,
		int	coarsen_delay,
		int	coarsen_affect
	)

Set a parameter that delays coarsening after adaptation.

If positive each quadrant counts the number of adaptations it has survived. Calling this function initializes all quadrant counters to zero. On adaptation we only coarsen a quadrant if it is old enough. Optionally, we can also delay the time between subsequent coarsenings.

Parameters

[in,out]	pp	A valid p8est_wrap structure.
[in]	coarsen_delay	Set how many adaptation cycles a quadrant has to wait to be allowed to coarsen. Non-negative number; 0 disables the feature. Suggested default value: not larger than 2.
[in]	coarsen_affect	Boolean; If true, we not only count from the most recent refinement but also between subsequent coarsenings. Suggested default: 0.

◆ p8est_wrap_set_hollow()

void p8est_wrap_set_hollow	(	p8est_wrap_t *	pp,
		int	hollow
	)

Change hollow status of the wrap.

It is legal to set to the current hollow status.

Parameters

[in,out]	pp	The present wrap structure, hollow or not.
[in]	hollow	The desired hollow status.

◆ p8est_wrap_set_partitioning()

void p8est_wrap_set_partitioning	(	p8est_wrap_t *	pp,
		int	partition_for_coarsening
	)

Set a parameter that ensures future partitions allow one level of coarsening.

The partition_for_coarsening parameter is passed to p8est_partition_ext in p8est_wrap_partition. If not zero, all future calls to p8est_wrap_partition will partition in a manner that allows one level of coarsening. This function does not automatically repartition the mesh, when switching partition_for_coarsening to a non-zero value.

Parameters

[in,out]	pp	A valid p8est_wrap structure.
[in]	partition_for_coarsening	Boolean: If true, all future partitions of the wrap allow one level of coarsening. Suggested default: 1.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Function Documentation

◆ p8est_wrap_adapt()

◆ p8est_wrap_complete()

◆ p8est_wrap_get_ghost()

◆ p8est_wrap_get_mesh()

◆ p8est_wrap_mark_coarsen()

◆ p8est_wrap_mark_refine()

◆ p8est_wrap_new_conn()

◆ p8est_wrap_new_copy()

◆ p8est_wrap_new_ext()

◆ p8est_wrap_new_p8est()

◆ p8est_wrap_new_p8est_params()

◆ p8est_wrap_new_params()

◆ p8est_wrap_new_unitcube()

◆ p8est_wrap_params_init()

◆ p8est_wrap_partition()

◆ p8est_wrap_set_coarsen_delay()

◆ p8est_wrap_set_hollow()

◆ p8est_wrap_set_partitioning()