The top-level 2D p4est interface. More...

#include <p4est_connectivity.h>

Include dependency graph for p4est.h:

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

Data Structures
struct	p4est_quadrant
	The 2D quadrant datatype. More...

union	p4est_quadrant::p4est_quadrant_data

struct	p4est_tree
	The p4est tree datatype. More...

struct	p4est
	The p4est forest datatype. More...

Macros
#define	P4EST_OLD_MAXLEVEL 30 /* in 2D, the maxlevel has always been 30 */
	The finest level of the quadtree for representing nodes.

#define	P4EST_MAXLEVEL 30

#define	P4EST_OLD_QMAXLEVEL 29 /* in 2D, the qmaxlevel has always been 29 */
	The finest level of the quadtree for representing quadrants.

#define	P4EST_QMAXLEVEL 29

#define	P4EST_ROOT_LEN ((p4est_qcoord_t) 1 << P4EST_MAXLEVEL)
	The length of a side of the root quadrant.

#define	P4EST_QUADRANT_LEN(l) ((p4est_qcoord_t) 1 << (P4EST_MAXLEVEL - (l)))
	The length of a quadrant of level l.

#define	P4EST_QUADRANT_MASK(l) (~(P4EST_QUADRANT_LEN (l) - 1))
	Create a mask of 1-bits from the left and maxlevel-level zero bits.

#define	P4EST_LAST_OFFSET(l) (P4EST_ROOT_LEN - P4EST_QUADRANT_LEN (l))
	The offset of the highest (farthest from the origin) quadrant at level l.

#define	P4EST_QUADRANT_INIT(q) ((void) memset ((q), -1, sizeof (p4est_quadrant_t)))
	set statically allocated quadrant to defined values

Typedefs
typedef struct p4est_quadrant	p4est_quadrant_t
	The 2D quadrant datatype.

typedef struct p4est_tree	p4est_tree_t
	The p4est tree datatype.

typedef struct p4est_inspect	p4est_inspect_t
	Data pertaining to selecting, inspecting, and profiling algorithms. More...

typedef struct p4est	p4est_t
	The p4est forest datatype.

typedef void(*	p4est_init_t) (p4est_t p4est, p4est_topidx_t which_tree, p4est_quadrant_t quadrant)
	Callback function prototype to initialize the quadrant's user data. More...

typedef int(*	p4est_refine_t) (p4est_t p4est, p4est_topidx_t which_tree, p4est_quadrant_t quadrant)
	Callback function prototype to decide for refinement. More...

typedef int(*	p4est_coarsen_t) (p4est_t p4est, p4est_topidx_t which_tree, p4est_quadrant_t quadrants[])
	Callback function prototype to decide for coarsening. More...

typedef int(*	p4est_weight_t) (p4est_t p4est, p4est_topidx_t which_tree, p4est_quadrant_t quadrant)
	Callback function prototype to calculate weights for partitioning. More...

Functions
size_t	p4est_memory_used (p4est_t *p4est)
	Calculate local memory usage of a forest structure. More...

long	p4est_revision (p4est_t *p4est)
	Return the revision counter of the forest. More...

void	p4est_qcoord_to_vertex (p4est_connectivity_t *connectivity, p4est_topidx_t treeid, p4est_qcoord_t x, p4est_qcoord_t y, double vxyz[3])
	Transform a quadrant coordinate into the space spanned by tree vertices. More...

p4est_t *	p4est_new (sc_MPI_Comm mpicomm, p4est_connectivity_t connectivity, size_t data_size, p4est_init_t init_fn, void user_pointer)
	Create a new forest with an initial coarse mesh. More...

void	p4est_destroy (p4est_t *p4est)
	Destroy a p4est. More...

p4est_t *	p4est_copy (p4est_t *input, int copy_data)
	Make a deep copy of a p4est. More...

void	p4est_reset_data (p4est_t p4est, size_t data_size, p4est_init_t init_fn, void user_pointer)
	Reset user pointer and element data. More...

void	p4est_refine (p4est_t *p4est, int refine_recursive, p4est_refine_t refine_fn, p4est_init_t init_fn)
	Refine a forest. More...

void	p4est_coarsen (p4est_t *p4est, int coarsen_recursive, p4est_coarsen_t coarsen_fn, p4est_init_t init_fn)
	Coarsen a forest. More...

void	p4est_balance (p4est_t *p4est, p4est_connect_type_t btype, p4est_init_t init_fn)
	2:1 balance the size differences of neighboring elements in a forest. More...

void	p4est_partition (p4est_t *p4est, int allow_for_coarsening, p4est_weight_t weight_fn)
	Equally partition the forest. More...

unsigned	p4est_checksum (p4est_t *p4est)
	Compute the checksum for a forest. More...

unsigned	p4est_checksum_partition (p4est_t *p4est)
	Compute a partition-dependent checksum for a forest. More...

void	p4est_save (const char filename, p4est_t p4est, int save_data)
	Save the complete connectivity/p4est data to disk. More...

p4est_t *	p4est_load (const char filename, sc_MPI_Comm mpicomm, size_t data_size, int load_data, void user_pointer, p4est_connectivity_t **connectivity)
	Load the complete connectivity/p4est structure from disk. More...

Variables
void *	P4EST_DATA_UNINITIALIZED

Detailed Description

The top-level 2D p4est interface.

Typedef Documentation

◆ p4est_coarsen_t

typedef int(* p4est_coarsen_t) (p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrants[])

Callback function prototype to decide for coarsening.

Parameters

[in]	p4est	the forest
[in]	which_tree	the tree containing quadrant
[in]	quadrants	Pointers to 4 siblings in Morton ordering.

Returns: nonzero if the quadrants shall be replaced with their parent.

Examples: simple/simple2.c.

◆ p4est_init_t

typedef void(* p4est_init_t) (p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)

Callback function prototype to initialize the quadrant's user data.

Parameters

[in]	p4est	the forest
[in]	which_tree	the tree containing quadrant
[in,out]	quadrant	the quadrant to be initialized: if data_size > 0, the data to be initialized is at quadrant->p.user_data; otherwise, the non-pointer user data (such as quadrant->p.user_int) can be initialized

◆ p4est_inspect_t

typedef struct p4est_inspect p4est_inspect_t

Data pertaining to selecting, inspecting, and profiling algorithms.

A pointer to this structure is hooked into the p4est main structure. Declared in p4est_extended.h. Used to profile important algorithms.

◆ p4est_refine_t

typedef int(* p4est_refine_t) (p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)

Callback function prototype to decide for refinement.

Parameters

[in]	p4est	the forest
[in]	which_tree	the tree containing quadrant
[in]	quadrant	the quadrant that may be refined

Returns: nonzero if the quadrant shall be refined.

Examples: simple/simple2.c.

◆ p4est_weight_t

typedef int(* p4est_weight_t) (p4est_t *p4est, p4est_topidx_t which_tree, p4est_quadrant_t *quadrant)

Callback function prototype to calculate weights for partitioning.

Parameters

[in]	p4est	the forest
[in]	which_tree	the tree containing quadrant

Returns: a 32bit integer >= 0 as the quadrant weight.

Note: Global sum of weights must fit into a 64bit integer.

Function Documentation

◆ p4est_balance()

void p4est_balance	(	p4est_t *	p4est,
		p4est_connect_type_t	btype,
		p4est_init_t	init_fn
	)

2:1 balance the size differences of neighboring elements in a forest.

Parameters

[in,out]	p4est	The p4est to be worked on.
[in]	btype	Balance type (face or corner/full). Corner balance is almost never required when discretizing a PDE; just causes smoother mesh grading.
[in]	init_fn	Callback function to initialize the user_data which is already allocated automatically.

Examples: simple/simple2.c, and steps/p4est_step1.c.

◆ p4est_checksum()

unsigned p4est_checksum ( p4est_t * p4est )

Compute the checksum for a forest.

Based on quadrant arrays only. It is independent of partition and mpisize.

Returns: Returns the checksum on all processors.

Examples: simple/simple2.c.

◆ p4est_checksum_partition()

unsigned p4est_checksum_partition ( p4est_t * p4est )

Compute a partition-dependent checksum for a forest.

Returns: Returns the checksum on all processors.

◆ p4est_coarsen()

void p4est_coarsen	(	p4est_t *	p4est,
		int	coarsen_recursive,
		p4est_coarsen_t	coarsen_fn,
		p4est_init_t	init_fn
	)

Coarsen a forest.

Parameters

[in,out]	p4est	The forest is changed in place.
[in]	coarsen_recursive	Boolean to decide on recursive coarsening.
[in]	coarsen_fn	Callback function that returns true if a family of quadrants shall be coarsened
[in]	init_fn	Callback function to initialize the user_data which is already allocated automatically.

Examples: simple/simple2.c.

◆ p4est_copy()

p4est_t * p4est_copy	(	p4est_t *	input,
		int	copy_data
	)

Make a deep copy of a p4est.

The connectivity is not duplicated. Copying of quadrant user data is optional. If old and new data sizes are 0, the user_data field is copied regardless. The inspect member of the copy is set to NULL. The revision counter of the copy is set to zero.

Parameters

[in] copy_data If true, data are copied. If false, data_size is set to 0.

Returns: Returns a valid p4est that does not depend on the input, except for borrowing the same connectivity. Its revision counter is 0.

◆ p4est_destroy()

void p4est_destroy ( p4est_t * p4est )

Destroy a p4est.

Note: The connectivity structure is not destroyed with the p4est.

Examples: simple/simple2.c, and steps/p4est_step1.c.

◆ p4est_load()

p4est_t * p4est_load	(	const char *	filename,
		sc_MPI_Comm	mpicomm,
		size_t	data_size,
		int	load_data,
		void *	user_pointer,
		p4est_connectivity_t **	connectivity
	)

Load the complete connectivity/p4est structure from disk.

This is a collective operation that all MPI processes need to call. All processes read from the same file, so the filename given needs to be identical over all parallel invocations.

By default, a file can only be loaded with the same number of processors that it was stored with. The defaults can be changed with p4est_load_ext() in p4est_extended.h.

The revision counter of the loaded p4est is set to zero.

Parameters

[in]	filename	Name of the file to read.
[in]	mpicomm	A valid MPI communicator.
[in]	data_size	Size of data for each quadrant which can be zero. Then user_data_pool is set to NULL. If data_size is zero, load_data is ignored.
[in]	load_data	If true, the element data is loaded. This is only permitted if the saved data size matches. If false, the stored data size is ignored.
[in]	user_pointer	Assign to the user_pointer member of the p4est before init_fn is called the first time.
[out]	connectivity	Connectivity must be destroyed separately.

Returns: Returns a valid forest structure. A pointer to a valid connectivity structure is returned through the last argument.

Note: Aborts on file errors or invalid file contents.

◆ p4est_memory_used()

size_t p4est_memory_used ( p4est_t * p4est )

Calculate local memory usage of a forest structure.

Not collective. The memory used on the current rank is returned. The connectivity structure is not counted since it is not owned; use p4est_connectivity_memory_usage (p4est->connectivity).

Parameters

[in] p4est Valid forest structure.

Returns: Memory used in bytes.

◆ p4est_new()

p4est_t * p4est_new	(	sc_MPI_Comm	mpicomm,
		p4est_connectivity_t *	connectivity,
		size_t	data_size,
		p4est_init_t	init_fn,
		void *	user_pointer
	)

Create a new forest with an initial coarse mesh.

The new forest consists of equi-partitioned root quadrants. When there are more processors than trees, some processors are empty.

Parameters

[in]	mpicomm	A valid MPI communicator.
[in]	connectivity	This is the connectivity information that the forest is built with. Note the p4est does not take ownership of the memory.
[in]	data_size	This is the size of data for each quadrant which can be zero. Then user_data_pool is set to NULL.
[in]	init_fn	Callback function to initialize the user_data which is already allocated automatically.
[in]	user_pointer	Assign to the user_pointer member of the p4est before init_fn is called the first time.

Returns: This returns a valid forest.

Note: The connectivity structure must not be destroyed during the lifetime of this forest.

Examples: steps/p4est_step1.c.

◆ p4est_partition()

void p4est_partition	(	p4est_t *	p4est,
		int	allow_for_coarsening,
		p4est_weight_t	weight_fn
	)

Equally partition the forest.

The partition can be by element count or by a user-defined weight.

The forest will be partitioned between processors such that they have an approximately equal number of quadrants (or sum of weights).

On one process, the function noops and does not call the weight callback. Otherwise, the weight callback is called once per quadrant in order.

Parameters

[in,out]	p4est	The forest that will be partitioned.
[in]	allow_for_coarsening	Slightly modify partition such that quadrant families are not split between ranks.
[in]	weight_fn	A weighting function or NULL for uniform partitioning. When running with mpisize == 1, never called. Otherwise, called in order for all quadrants if not NULL. A weighting function with constant weight 1 on each quadrant is equivalent to weight_fn == NULL but other constant weightings may result in different uniform partitionings.

Examples: simple/simple2.c, and steps/p4est_step1.c.

◆ p4est_qcoord_to_vertex()

void p4est_qcoord_to_vertex	(	p4est_connectivity_t *	connectivity,
		p4est_topidx_t	treeid,
		p4est_qcoord_t	x,
		p4est_qcoord_t	y,
		double	vxyz[3]
	)

Transform a quadrant coordinate into the space spanned by tree vertices.

Parameters

[in]	connectivity	Connectivity must provide the vertices.
[in]	treeid	Identify the tree that contains x, y.
[in]	x,y	Quadrant coordinates relative to treeid.
[out]	vxyz	Transformed coordinates in vertex space.

◆ p4est_refine()

void p4est_refine	(	p4est_t *	p4est,
		int	refine_recursive,
		p4est_refine_t	refine_fn,
		p4est_init_t	init_fn
	)

Refine a forest.

Parameters

[in,out]	p4est	The forest is changed in place.
[in]	refine_recursive	Boolean to decide on recursive refinement.
[in]	refine_fn	Callback function that must return true if a quadrant shall be refined. If refine_recursive is true, refine_fn is called for every existing and newly created quadrant. Otherwise, it is called for every existing quadrant. It is possible that a refinement request made by the callback is ignored. To catch this case, you can examine whether init_fn gets called, or use p4est_refine_ext in p4est_extended.h and examine whether replace_fn gets called.
[in]	init_fn	Callback function to initialize the user_data of newly created quadrants, which is already allocated. This function pointer may be NULL.

Examples: simple/simple2.c, and steps/p4est_step1.c.

◆ p4est_reset_data()

void p4est_reset_data	(	p4est_t *	p4est,
		size_t	data_size,
		p4est_init_t	init_fn,
		void *	user_pointer
	)

Reset user pointer and element data.

When the data size is changed the quadrant data is freed and allocated. The initialization callback is invoked on each quadrant. Old user_data content is disregarded.

Parameters

[in]	data_size	This is the size of data for each quadrant which can be zero. Then user_data_pool is set to NULL.
[in]	init_fn	Callback function to initialize the user_data which is already allocated automatically. May be NULL.
[in]	user_pointer	Assign to the user_pointer member of the p4est before init_fn is called the first time.

◆ p4est_revision()

long p4est_revision ( p4est_t * p4est )

Return the revision counter of the forest.

Not collective, even though the revision value is the same on all ranks. A newly created forest starts with a revision counter of zero. Every refine, coarsen, partition, and balance that actually changes the mesh increases the counter by one. Operations with no effect keep the old value.

Parameters

[in] p8est The forest must be valid.

Returns: Non-negative number.

◆ p4est_save()

void p4est_save	(	const char *	filename,
		p4est_t *	p4est,
		int	save_data
	)

Save the complete connectivity/p4est data to disk.

This is a collective operation that all MPI processes need to call. All processes write into the same file, so the filename given needs to be identical over all parallel invocations.

By default, we write the current processor count and partition into the file header. This makes the file depend on mpisize. For changing this see p4est_save_ext() in p4est_extended.h.

The revision counter is not saved to the file, since that would make files different that come from different revisions but store the same mesh.

Parameters

[in]	filename	Name of the file to write.
[in]	p4est	Valid forest structure.
[in]	save_data	If true, the element data is saved. Otherwise, a data size of 0 is saved.

Note: Aborts on file errors.; If p4est is not configured to use MPI-IO, some processes return from this function before the file is complete, in which case immediate read-access to the file may require a call to sc_MPI_Barrier.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ p4est_coarsen_t

◆ p4est_init_t

◆ p4est_inspect_t

◆ p4est_refine_t

◆ p4est_weight_t

Function Documentation

◆ p4est_balance()

◆ p4est_checksum()

◆ p4est_checksum_partition()

◆ p4est_coarsen()

◆ p4est_copy()

◆ p4est_destroy()

◆ p4est_load()

◆ p4est_memory_used()

◆ p4est_new()

◆ p4est_partition()

◆ p4est_qcoord_to_vertex()

◆ p4est_refine()

◆ p4est_reset_data()

◆ p4est_revision()

◆ p4est_save()