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

#include <p4est_extended.h>
#include <sc_refcount.h>

Include dependency graph for p4est_wrap.h:

Go to the source code of this file.

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

struct	p4est_wrap

struct	p4est_wrap_leaf

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

Typedefs
typedef enum p4est_wrap_flags	p4est_wrap_flags_t

typedef struct p4est_wrap	p4est_wrap_t

typedef struct p4est_wrap_leaf	p4est_wrap_leaf_t

Enumerations
enum	p4est_wrap_flags { P4EST_WRAP_NONE = 0 , P4EST_WRAP_REFINE = 0x01 , P4EST_WRAP_COARSEN = 0x02 }

Functions
void	p4est_wrap_params_init (p4est_wrap_params_t *params)
	Initialize a default p4est_wrap_params_t structure. More...

p4est_wrap_t *	p4est_wrap_new_conn (sc_MPI_Comm mpicomm, p4est_connectivity_t *conn, int initial_level)
	Create a p4est wrapper from a given connectivity structure. More...

p4est_wrap_t *	p4est_wrap_new_p4est (p4est_t p4est, int hollow, p4est_connect_type_t btype, p4est_replace_t replace_fn, void user_pointer)
	Create a wrapper for a given p4est structure. More...

p4est_wrap_t *	p4est_wrap_new_p4est_params (p4est_t p4est, p4est_wrap_params_t params)
	Create a wrapper for a given p4est structure. More...

p4est_wrap_t *	p4est_wrap_new_ext (sc_MPI_Comm mpicomm, p4est_connectivity_t conn, int initial_level, int hollow, p4est_connect_type_t btype, p4est_replace_t replace_fn, void user_pointer)
	Create a p4est wrapper from a given connectivity structure. More...

p4est_wrap_t *	p4est_wrap_new_params (sc_MPI_Comm mpicomm, p4est_connectivity_t conn, int initial_level, p4est_wrap_params_t params)
	Create a p4est wrapper from a given connectivity structure. More...

p4est_wrap_t *	p4est_wrap_new_copy (p4est_wrap_t source, size_t data_size, p4est_replace_t replace_fn, void user_pointer)
	Create a p4est wrapper from an existing one. More...

p4est_wrap_t *	p4est_wrap_new_unitsquare (sc_MPI_Comm mpicomm, int initial_level)
	Create p4est and auxiliary data structures. More...

p4est_wrap_t *	p4est_wrap_new_periodic (sc_MPI_Comm mpicomm, int initial_level)

p4est_wrap_t *	p4est_wrap_new_rotwrap (sc_MPI_Comm mpicomm, int initial_level)

p4est_wrap_t *	p4est_wrap_new_corner (sc_MPI_Comm mpicomm, int initial_level)

p4est_wrap_t *	p4est_wrap_new_pillow (sc_MPI_Comm mpicomm, int initial_level)

p4est_wrap_t *	p4est_wrap_new_moebius (sc_MPI_Comm mpicomm, int initial_level)

p4est_wrap_t *	p4est_wrap_new_cubed (sc_MPI_Comm mpicomm, int initial_level)

p4est_wrap_t *	p4est_wrap_new_disk (sc_MPI_Comm mpicomm, int px, int py, int initial_level)

p4est_wrap_t *	p4est_wrap_new_brick (sc_MPI_Comm mpicomm, int bx, int by, int px, int py, int initial_level)

p4est_wrap_t *	p4est_wrap_new_world (int initial_level)
	Passes sc_MPI_COMM_WORLD to p4est_wrap_new_unitsquare.

void	p4est_wrap_destroy (p4est_wrap_t *pp)

void	p4est_wrap_set_hollow (p4est_wrap_t *pp, int hollow)
	Change hollow status of the wrap. More...

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

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

p4est_ghost_t *	p4est_wrap_get_ghost (p4est_wrap_t *pp)
	Return the appropriate ghost layer. More...

p4est_mesh_t *	p4est_wrap_get_mesh (p4est_wrap_t *pp)
	Return the appropriate mesh structure. More...

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

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

int	p4est_wrap_adapt (p4est_wrap_t *pp)
	Call p4est_refine, coarsen, and balance to update pp->p4est. More...

int	p4est_wrap_partition (p4est_wrap_t pp, int weight_exponent, p4est_locidx_t unchanged_first, p4est_locidx_t unchanged_length, p4est_locidx_t unchanged_old_first)
	Call p4est_partition for equal leaf distribution. More...

void	p4est_wrap_complete (p4est_wrap_t *pp)
	Free memory for the intermediate mesh. More...

p4est_wrap_leaf_t *	p4est_wrap_leaf_first (p4est_wrap_t *pp, int track_mirrors)

p4est_wrap_leaf_t *	p4est_wrap_leaf_next (p4est_wrap_leaf_t *leaf)

Detailed Description

The logic in p4est_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

◆ p4est_wrap_adapt()

int p4est_wrap_adapt ( p4est_wrap_t * pp )

Call p4est_refine, coarsen, and balance to update pp->p4est.

Checks pp->flags as per-quadrant input against p4est_wrap_flags_t. The pp->flags array is updated along with p4est 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 p4est canceled out and skips computing ghost_aux and mesh_aux when possible.

Parameters

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

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

◆ p4est_wrap_complete()

void p4est_wrap_complete ( p4est_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 p4est wrapper to work with, must not be hollow.

◆ p4est_wrap_get_ghost()

p4est_ghost_t * p4est_wrap_get_ghost ( p4est_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] pp Must have !pp->hollow.

◆ p4est_wrap_get_mesh()

p4est_mesh_t * p4est_wrap_get_mesh ( p4est_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] pp Must have !pp->hollow.

◆ p4est_wrap_mark_coarsen()

void p4est_wrap_mark_coarsen	(	p4est_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 p4est 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.

◆ p4est_wrap_mark_refine()

void p4est_wrap_mark_refine	(	p4est_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 p4est 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.

◆ p4est_wrap_new_conn()

p4est_wrap_t * p4est_wrap_new_conn	(	sc_MPI_Comm	mpicomm,
		p4est_connectivity_t *	conn,
		int	initial_level
	)

Create a p4est wrapper from a given connectivity structure.

The ghost and mesh members are initialized as well as the flags. The btype is set to P4EST_CONNECT_FULL. This function sets a subset of the wrap creation parameters. For full control use p4est_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 p4est_wrap structure.

◆ p4est_wrap_new_copy()

p4est_wrap_t * p4est_wrap_new_copy	(	p4est_wrap_t *	source,
		size_t	data_size,
		p4est_replace_t	replace_fn,
		void *	user_pointer
	)

Create a p4est wrapper from an existing one.

Note: This wrapper must be destroyed before the original one. We set it to hollow and copy the original p4est 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 p4est_wrap_adapt. May be NULL.
[in]	user_pointer	Set the user pointer in p4est_wrap_t. Subsequently, we will never access it.

Returns: A fully initialized p4est_wrap structure.

◆ p4est_wrap_new_ext()

p4est_wrap_t * p4est_wrap_new_ext	(	sc_MPI_Comm	mpicomm,
		p4est_connectivity_t *	conn,
		int	initial_level,
		int	hollow,
		p4est_connect_type_t	btype,
		p4est_replace_t	replace_fn,
		void *	user_pointer
	)

Create a p4est wrapper from a given connectivity structure.

Like p4est_wrap_new_conn, but with extra parameters hollow and btype. This function sets a subset of the wrap creation parameters. For full control use p4est_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 p4est_wrap_adapt. May be NULL.
[in]	user_pointer	Set the user pointer in p4est_wrap_t. Subsequently, we will never access it.

Returns: A fully initialized p4est_wrap structure.

◆ p4est_wrap_new_p4est()

p4est_wrap_t * p4est_wrap_new_p4est	(	p4est_t *	p4est,
		int	hollow,
		p4est_connect_type_t	btype,
		p4est_replace_t	replace_fn,
		void *	user_pointer
	)

Create a wrapper for a given p4est structure.

Parameters

[in,out]	p4est	Valid p4est 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 p4est_wrap_adapt. May be NULL.
[in]	user_pointer	Set the user pointer in p4est_wrap_t. Subsequently, we will never access it.

Returns: A fully initialized p4est_wrap structure.

◆ p4est_wrap_new_p4est_params()

p4est_wrap_t * p4est_wrap_new_p4est_params	(	p4est_t *	p4est,
		p4est_wrap_params_t *	params
	)

Create a wrapper for a given p4est structure.

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

Parameters

[in,out]	p4est	Valid p4est 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 p4est_wrap_params_init.

Returns: A fully initialized p4est_wrap structure.

◆ p4est_wrap_new_params()

p4est_wrap_t * p4est_wrap_new_params	(	sc_MPI_Comm	mpicomm,
		p4est_connectivity_t *	conn,
		int	initial_level,
		p4est_wrap_params_t *	params
	)

Create a p4est wrapper from a given connectivity structure.

Like p4est_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 p4est_wrap_params_init.

Returns: A fully initialized p4est_wrap structure.

◆ p4est_wrap_new_unitsquare()

p4est_wrap_t * p4est_wrap_new_unitsquare	(	sc_MPI_Comm	mpicomm,
		int	initial_level
	)

Create p4est and auxiliary data structures.

Expects sc_MPI_Init to be called beforehand.

◆ p4est_wrap_params_init()

void p4est_wrap_params_init ( p4est_wrap_params_t * params )

Initialize a default p4est_wrap_params_t structure.

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

◆ p4est_wrap_partition()

int p4est_wrap_partition	(	p4est_wrap_t *	pp,
		int	weight_exponent,
		p4est_locidx_t *	unchanged_first,
		p4est_locidx_t *	unchanged_length,
		p4est_locidx_t *	unchanged_old_first
	)

Call p4est_partition for equal leaf distribution.

Frees the old ghost and mesh first and updates pp->flags along with p4est. The pp->flags array is reset to zeros. Creates ghost and mesh to represent the new mesh.

Parameters

[in,out]	pp	The p4est 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 p4est has changed. If true, complete must be called. If false, complete must not be called.

◆ p4est_wrap_set_coarsen_delay()

void p4est_wrap_set_coarsen_delay	(	p4est_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 p4est_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.

◆ p4est_wrap_set_hollow()

void p4est_wrap_set_hollow	(	p4est_wrap_t *	pp,
		int	hollow
	)

Change hollow status of the wrap.

A wrap is hollow if the flags, ghost, and mesh members are NULL. Legal to set to current hollow status, in which case wrap is not changed. If changed from not hollow to hollow, previously set refinement and coarsening flags are zeroed.

Parameters

[in,out]	pp	The present wrap structure, hollow or not.
[in]	hollow	The desired hollow status. If set to hollow, refinement flags are zeroed.

◆ p4est_wrap_set_partitioning()

void p4est_wrap_set_partitioning	(	p4est_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 p4est_partition_ext in p4est_wrap_partition. If not zero, all future calls to p4est_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 p4est_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

◆ p4est_wrap_adapt()

◆ p4est_wrap_complete()

◆ p4est_wrap_get_ghost()

◆ p4est_wrap_get_mesh()

◆ p4est_wrap_mark_coarsen()

◆ p4est_wrap_mark_refine()

◆ p4est_wrap_new_conn()

◆ p4est_wrap_new_copy()

◆ p4est_wrap_new_ext()

◆ p4est_wrap_new_p4est()

◆ p4est_wrap_new_p4est_params()

◆ p4est_wrap_new_params()

◆ p4est_wrap_new_unitsquare()

◆ p4est_wrap_params_init()

◆ p4est_wrap_partition()

◆ p4est_wrap_set_coarsen_delay()

◆ p4est_wrap_set_hollow()

◆ p4est_wrap_set_partitioning()