The top-level 3D p8est interface. More...

#include <p8est_connectivity.h>

Include dependency graph for p8est.h:

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

Data Structures
struct	p8est_quadrant
	The 3D quadrant (i.e., octant) datatype. More...

union	p8est_quadrant::p8est_quadrant_data

struct	p8est_tree
	The p8est tree datatype. More...

struct	p8est
	The p8est forest datatype. More...

Macros
#define	P8EST_OLD_MAXLEVEL 19 /* old means prior to mid-2020 */
	The finest level of the octree for representing nodes.

#define	P8EST_MAXLEVEL 30

#define	P8EST_OLD_QMAXLEVEL 18 /* old means prior to mid-2020 */
	The finest level of the octree for representing octants.

#define	P8EST_QMAXLEVEL 29

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

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

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

#define	P8EST_LAST_OFFSET(l) (P8EST_ROOT_LEN - P8EST_QUADRANT_LEN (l))
	The offset of the highest (farthest from the origin) quadrant at level l.

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

Typedefs
typedef struct p8est_quadrant	p8est_quadrant_t
	The 3D quadrant (i.e., octant) datatype.

typedef struct p8est_tree	p8est_tree_t
	The p8est tree datatype.

typedef struct p8est_inspect	p8est_inspect_t
	Data pertaining to selecting, inspecting, and profiling algorithms. More...

typedef struct p8est	p8est_t
	The p8est forest datatype.

typedef void(*	p8est_init_t) (p8est_t p8est, p4est_topidx_t which_tree, p8est_quadrant_t quadrant)
	Callback function prototype to initialize the quadrant's user data. More...

typedef int(*	p8est_refine_t) (p8est_t p8est, p4est_topidx_t which_tree, p8est_quadrant_t quadrant)
	Callback function prototype to decide for refinement. More...

typedef int(*	p8est_coarsen_t) (p8est_t p8est, p4est_topidx_t which_tree, p8est_quadrant_t quadrants[])
	Callback function prototype to decide for coarsening. More...

typedef int(*	p8est_weight_t) (p8est_t p8est, p4est_topidx_t which_tree, p8est_quadrant_t quadrant)
	Callback function prototype to calculate weights for partitioning. More...

Functions
size_t	p8est_memory_used (p8est_t *p8est)
	Calculate local memory usage of a forest structure. More...

long	p8est_revision (p8est_t *p8est)
	Return the revision counter of the forest. More...

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

p8est_t *	p8est_new (sc_MPI_Comm mpicomm, p8est_connectivity_t connectivity, size_t data_size, p8est_init_t init_fn, void user_pointer)
	Create a new forest with an initial coarse mesh. More...

void	p8est_destroy (p8est_t *p8est)
	Destroy a p8est. More...

p8est_t *	p8est_copy (p8est_t *input, int copy_data)
	Make a deep copy of a p8est. More...

void	p8est_reset_data (p8est_t p8est, size_t data_size, p8est_init_t init_fn, void user_pointer)
	Reset user pointer and element data. More...

void	p8est_refine (p8est_t *p8est, int refine_recursive, p8est_refine_t refine_fn, p8est_init_t init_fn)
	Refine a forest. More...

void	p8est_coarsen (p8est_t *p8est, int coarsen_recursive, p8est_coarsen_t coarsen_fn, p8est_init_t init_fn)
	Coarsen a forest. More...

void	p8est_balance (p8est_t *p8est, p8est_connect_type_t btype, p8est_init_t init_fn)
	2:1 balance the size differences of neighboring elements in a forest. More...

void	p8est_partition (p8est_t *p8est, int allow_for_coarsening, p8est_weight_t weight_fn)
	Equally partition the forest. More...

unsigned	p8est_checksum (p8est_t *p8est)
	Compute the checksum for a forest. More...

unsigned	p8est_checksum_partition (p8est_t *p8est)
	Compute a partition-dependent checksum for a forest. More...

void	p8est_save (const char filename, p8est_t p8est, int save_data)
	Save the complete connectivity/p8est data to disk. More...

p8est_t *	p8est_load (const char filename, sc_MPI_Comm mpicomm, size_t data_size, int load_data, void user_pointer, p8est_connectivity_t **connectivity)
	Load the complete connectivity/p8est structure from disk. More...

Variables
void *	P8EST_DATA_UNINITIALIZED

Detailed Description

The top-level 3D p8est interface.

Typedef Documentation

◆ p8est_coarsen_t

typedef int(* p8est_coarsen_t) (p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrants[])

Callback function prototype to decide for coarsening.

Parameters

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

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

Examples: simple/simple3.c.

◆ p8est_init_t

typedef void(* p8est_init_t) (p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)

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

Parameters

[in]	p8est	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

◆ p8est_inspect_t

typedef struct p8est_inspect p8est_inspect_t

Data pertaining to selecting, inspecting, and profiling algorithms.

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

◆ p8est_refine_t

typedef int(* p8est_refine_t) (p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)

Callback function prototype to decide for refinement.

Parameters

[in]	p8est	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/simple3.c.

◆ p8est_weight_t

typedef int(* p8est_weight_t) (p8est_t *p8est, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)

Callback function prototype to calculate weights for partitioning.

Parameters

[in]	p8est	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

◆ p8est_balance()

void p8est_balance	(	p8est_t *	p8est,
		p8est_connect_type_t	btype,
		p8est_init_t	init_fn
	)

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

Parameters

[in,out]	p8est	The p8est to be worked on.
[in]	btype	Balance type (face, edge, or corner/full). Examples: Finite volume or discontinuous Galerkin methods only require face balance. Continuous finite element methods usually require edge balance. Corner balance is almost never required mathematically; it just produces a smoother mesh grading.
[in]	init_fn	Callback function to initialize the user_data which is already allocated automatically.

Examples: simple/simple3.c.

◆ p8est_checksum()

unsigned p8est_checksum ( p8est_t * p8est )

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/simple3.c.

◆ p8est_checksum_partition()

unsigned p8est_checksum_partition ( p8est_t * p8est )

Compute a partition-dependent checksum for a forest.

Returns: Returns the checksum on all processors.

◆ p8est_coarsen()

void p8est_coarsen	(	p8est_t *	p8est,
		int	coarsen_recursive,
		p8est_coarsen_t	coarsen_fn,
		p8est_init_t	init_fn
	)

Coarsen a forest.

Parameters

[in,out]	p8est	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/simple3.c.

◆ p8est_copy()

p8est_t * p8est_copy	(	p8est_t *	input,
		int	copy_data
	)

Make a deep copy of a p8est.

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 p8est that does not depend on the input, except for borrowing the same connectivity. Its revision counter is 0.

◆ p8est_destroy()

void p8est_destroy ( p8est_t * p8est )

Destroy a p8est.

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

Examples: simple/simple3.c.

◆ p8est_load()

p8est_t * p8est_load	(	const char *	filename,
		sc_MPI_Comm	mpicomm,
		size_t	data_size,
		int	load_data,
		void *	user_pointer,
		p8est_connectivity_t **	connectivity
	)

Load the complete connectivity/p8est 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 p8est_load_ext() in p8est_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 p8est 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.

◆ p8est_memory_used()

size_t p8est_memory_used ( p8est_t * p8est )

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 p8est_connectivity_memory_usage (p8est->connectivity).

Parameters

[in] p8est Valid forest structure.

Returns: Memory used in bytes.

◆ p8est_new()

p8est_t * p8est_new	(	sc_MPI_Comm	mpicomm,
		p8est_connectivity_t *	connectivity,
		size_t	data_size,
		p8est_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 p8est 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 p8est 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.

◆ p8est_partition()

void p8est_partition	(	p8est_t *	p8est,
		int	allow_for_coarsening,
		p8est_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]	p8est	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/simple3.c.

◆ p8est_qcoord_to_vertex()

void p8est_qcoord_to_vertex	(	p8est_connectivity_t *	connectivity,
		p4est_topidx_t	treeid,
		p4est_qcoord_t	x,
		p4est_qcoord_t	y,
		p4est_qcoord_t	z,
		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, z.
[in]	x,y,z	Quadrant coordinates relative to treeid.
[out]	vxyz	Transformed coordinates in vertex space.

◆ p8est_refine()

void p8est_refine	(	p8est_t *	p8est,
		int	refine_recursive,
		p8est_refine_t	refine_fn,
		p8est_init_t	init_fn
	)

Refine a forest.

Parameters

[in,out]	p8est	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 p8est_refine_ext in p8est_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/simple3.c.

◆ p8est_reset_data()

void p8est_reset_data	(	p8est_t *	p8est,
		size_t	data_size,
		p8est_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 p8est before init_fn is called the first time.

◆ p8est_revision()

long p8est_revision ( p8est_t * p8est )

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.

◆ p8est_save()

void p8est_save	(	const char *	filename,
		p8est_t *	p8est,
		int	save_data
	)

Save the complete connectivity/p8est 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 p8est_save_ext() in p8est_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]	p8est	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

◆ p8est_coarsen_t

◆ p8est_init_t

◆ p8est_inspect_t

◆ p8est_refine_t

◆ p8est_weight_t

Function Documentation

◆ p8est_balance()

◆ p8est_checksum()

◆ p8est_checksum_partition()

◆ p8est_coarsen()

◆ p8est_copy()

◆ p8est_destroy()

◆ p8est_load()

◆ p8est_memory_used()

◆ p8est_new()

◆ p8est_partition()

◆ p8est_qcoord_to_vertex()

◆ p8est_refine()

◆ p8est_reset_data()

◆ p8est_revision()

◆ p8est_save()