p6est.h File Reference

A hybrid 2D+1D AMR extension. More...

#include <p4est.h>
#include <p8est_connectivity.h>

Include dependency graph for p6est.h:

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

Go to the source code of this file.

Data Structures
struct	p6est_connectivity
	This structure holds the 2D+1D inter-tree connectivity information. More...
struct	p2est_quadrant
	A 1D quadrant datatype: this is used to encode a "layer" of a column in the 2D+1D AMR scheme. More...
union	p2est_quadrant::p6est_quadrant_data
struct	p6est
	The p6est forest datatype. More...

Macros
#define	P2EST_QUADRANT_INIT(q)    ((void) memset ((q), -1, sizeof (p2est_quadrant_t)))
	set statically allocated quadrant to defined values
#define	P6EST_COLUMN_GET_RANGE(q, f, l)
#define	P6EST_COLUMN_SET_RANGE(q, f, l)

Typedefs
typedef struct p6est_connectivity	p6est_connectivity_t
	This structure holds the 2D+1D inter-tree connectivity information. More...
typedef struct p2est_quadrant	p2est_quadrant_t
	A 1D quadrant datatype: this is used to encode a "layer" of a column in the 2D+1D AMR scheme.
typedef struct p6est	p6est_t
	The p6est forest datatype.
typedef void(*	p6est_init_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column, p2est_quadrant_t *layer)
	Callback function prototype to initialize the layers's user data. More...
typedef void(*	p6est_replace_t) (p6est_t *p6est, p4est_topidx_t which_tree, int num_outcolumns, int num_outlayers, p4est_quadrant_t *outcolumns[], p2est_quadrant_t *outlayers[], int num_incolumns, int num_inlayers, p4est_quadrant_t *incolumns[], p2est_quadrant_t *inlayers[])
	Callback function prototype to transfer information from outgoing layers to incoming layers. More...
typedef int(*	p6est_refine_column_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column)
	Callback function prototype to decide whether to horizontally refine a column, i.e., horizontally refine all of the layers in the column. More...
typedef int(*	p6est_refine_layer_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column, p2est_quadrant_t *layer)
	Callback function prototype to decide whether to vertically refine a layer. More...
typedef int(*	p6est_coarsen_column_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *columns[])
	Callback function prototype to decide for horizontal coarsening. More...
typedef int(*	p6est_coarsen_layer_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column, p2est_quadrant_t *layers[])
	Callback function prototype to decide for vertical coarsening. More...
typedef int(*	p6est_weight_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column, p2est_quadrant_t *layer)
	Callback function prototype to calculate weights for partitioning. More...

Enumerations
enum	p6est_comm_tag_t {   P6EST_COMM_PARTITION = 1 ,   P6EST_COMM_GHOST ,   P6EST_COMM_BALANCE }

Functions
p6est_connectivity_t *	p6est_connectivity_new (p4est_connectivity_t *conn4, double *top_vertices, double height[3])
	Create a p6est_connectivity_t from a p4est_connectivity_t. More...
void	p6est_connectivity_destroy (p6est_connectivity_t *conn)
	Destroy a p6est_connectivity structure.
void	p6est_tree_get_vertices (p6est_connectivity_t *conn, p4est_topidx_t which_tree, double vertices[24])
	Get the vertices of the corners of a tree. More...
void	p6est_qcoord_to_vertex (p6est_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...
p6est_t *	p6est_new (sc_MPI_Comm mpicomm, p6est_connectivity_t *connectivity, size_t data_size, p6est_init_t init_fn, void *user_pointer)
	Create a new forest. More...
p6est_t *	p6est_new_from_p4est (p4est_t *p4est, double *top_vertices, double height[3], int min_zlevel, size_t data_size, p6est_init_t init_fn, void *user_pointer)
	Create a new forest from an already created p4est that represents columns. More...
void	p6est_destroy (p6est_t *p6est)
	Destroy a p6est. More...
p6est_t *	p6est_copy (p6est_t *input, int copy_data)
	Make a deep copy of a p6est. More...
void	p6est_reset_data (p6est_t *p6est, size_t data_size, p6est_init_t init_fn, void *user_pointer)
	Reset user pointer and element data. More...
void	p6est_refine_columns (p6est_t *p6est, int refine_recursive, p6est_refine_column_t refine_fn, p6est_init_t init_fn)
	Refine the columns of a sheet. More...
void	p6est_refine_layers (p6est_t *p6est, int refine_recursive, p6est_refine_layer_t refine_fn, p6est_init_t init_fn)
	Refine the layers within the columns of a sheet. More...
void	p6est_coarsen_columns (p6est_t *p6est, int coarsen_recursive, p6est_coarsen_column_t coarsen_fn, p6est_init_t init_fn)
	Coarsen the columns of a sheet. More...
void	p6est_coarsen_layers (p6est_t *p6est, int coarsen_recursive, p6est_coarsen_layer_t coarsen_fn, p6est_init_t init_fn)
	Coarsen the layers of a sheet. More...
void	p6est_balance (p6est_t *p6est, p8est_connect_type_t btype, p6est_init_t init_fn)
	Balance a forest. More...
p4est_gloidx_t	p6est_partition (p6est_t *p6est, p6est_weight_t weight_fn)
	Equally partition the forest. More...
void	p6est_partition_correct (p6est_t *p6est, p4est_locidx_t *num_layers_in_proc)
void	p6est_partition_to_p4est_partition (p6est_t *p6est, p4est_locidx_t *num_layers_in_proc, p4est_locidx_t *num_columns_in_proc)
void	p4est_partition_to_p6est_partition (p6est_t *p6est, p4est_locidx_t *num_columns_in_proc, p4est_locidx_t *num_layers_in_proc)
p4est_gloidx_t	p6est_partition_for_coarsening (p6est_t *p6est, p4est_locidx_t *num_layers_in_proc)
p4est_gloidx_t	p6est_partition_given (p6est_t *p6est, p4est_locidx_t *num_layers_in_proc)
unsigned	p6est_checksum (p6est_t *p6est)
	Compute the checksum for a forest. More...
void	p6est_save (const char *filename, p6est_t *p6est, int save_data)
	Save the complete connectivity/p6est data to disk. More...
p6est_t *	p6est_load (const char *filename, sc_MPI_Comm mpicomm, size_t data_size, int load_data, void *user_pointer, p6est_connectivity_t **connectivity)
	Load the complete connectivity/p6est structure from disk. More...
void	p6est_compress_columns (p6est_t *p6est)
void	p6est_update_offsets (p6est_t *p6est)

Variables
void *	P2EST_DATA_UNINITIALIZED

Detailed Description

A hybrid 2D+1D AMR extension.

Macro Definition Documentation

P6EST_COLUMN_GET_RANGE

#define P6EST_COLUMN_GET_RANGE	(		q,
			f,
			l
	)

Value:

  do {                                               \
    *(f) = (size_t) (q)->p.piggy3.local_num;         \
    *(l) = *(f) + (size_t) (q)->p.piggy3.which_tree; \
  } while (0);

P6EST_COLUMN_SET_RANGE

#define P6EST_COLUMN_SET_RANGE	(		q,
			f,
			l
	)

Value:

  do {                                                       \
    (q)->p.piggy3.local_num = (p4est_locidx_t) (f);          \
    (q)->p.piggy3.which_tree = (p4est_topidx_t) ((l) - (f)); \
  } while (0);

Typedef Documentation

p6est_coarsen_column_t

typedef int(* p6est_coarsen_column_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *columns[])

Callback function prototype to decide for horizontal coarsening.

Parameters

[in]

columns

Pointers to 4 sibling columns.

Returns

nonzero if the columns shall be replaced with their parent.

p6est_coarsen_layer_t

typedef int(* p6est_coarsen_layer_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column, p2est_quadrant_t *layers[])

Callback function prototype to decide for vertical coarsening.

Parameters

[in]

layers

Pointers to 2 vertical sibling layers.

Returns

nonzero if the layers shall be replaced with their parent.

p6est_connectivity_t

typedef struct p6est_connectivity p6est_connectivity_t

This structure holds the 2D+1D inter-tree connectivity information.

It is essentially a wrapper of the 2D p4est_connecitivity_t datatype, with some additional information about how the third dimension is embedded.

p6est_init_t

typedef void(* p6est_init_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column, p2est_quadrant_t *layer)

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

Parameters

[in]	p6est	the forest
[in]	which_tree	the tree in the forest
[in]	column	the column in the tree in the forest
[in]	layer	the layer in the column in the tree in the forest, whose user_data is to be initialized

p6est_refine_column_t

typedef int(* p6est_refine_column_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column)

Callback function prototype to decide whether to horizontally refine a column, i.e., horizontally refine all of the layers in the column.

Returns

nonzero if the layer shall be refined.

p6est_refine_layer_t

typedef int(* p6est_refine_layer_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column, p2est_quadrant_t *layer)

Callback function prototype to decide whether to vertically refine a layer.

Returns

nonzero if the layer shall be refined.

p6est_replace_t

typedef void(* p6est_replace_t) (p6est_t *p6est, p4est_topidx_t which_tree, int num_outcolumns, int num_outlayers, p4est_quadrant_t *outcolumns[], p2est_quadrant_t *outlayers[], int num_incolumns, int num_inlayers, p4est_quadrant_t *incolumns[], p2est_quadrant_t *inlayers[])

Callback function prototype to transfer information from outgoing layers to incoming layers.

This is used by extended routines when the layers of an existing, valid p6est are changed. The callback allows the user to make changes to newly initialized layers before the layers that they replace are destroyed.

Parameters

[in]	num_outcolumns	The number of columns that contain the outgoing layers: will be either 1 or 4.
[in]	num_outlayers	The number of outgoing layers: will be either 1 (a single layer is being refined), 2 (two layers are being vertically coarsened), or 4 (four layers are being horizontally coarsened).
[in]	outcolumns	The columns of the outgoing layers
[in]	outlayers	The outgoing layers: after the callback, the user_data, if p6est->data_size is nonzero, will be destroyed.
[in]	num_incolumns	The number of columns that contain the outgoing layers: will be either 1 or 4.
[in]	num_inlayers	The number of incoming layers: will be either 1 (coarsening), 2 (vertical refinement), or 4 (horizontal refinement)
[in]	incolumns	The columns of the incoming layers
[in,out]	inlayers	The incoming layers: prior to the callback, the user_data, if p6est->data_size is nonzero, is allocated, and the p6est_init_t callback, if it has been provided, will be called.

p6est_weight_t

typedef int(* p6est_weight_t) (p6est_t *p6est, p4est_topidx_t which_tree, p4est_quadrant_t *column, p2est_quadrant_t *layer)

Callback function prototype to calculate weights for partitioning.

Returns

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

Note

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

Function Documentation

p6est_balance()

void p6est_balance	(	p6est_t *	p6est,
		p8est_connect_type_t	btype,
		p6est_init_t	init_fn
	)

Balance a forest.

Parameters

[in]	p6est	The p6est to be worked on.
[in]	btype	Balance type (face, corner or default, full).
[in]	init_fn	Callback function to initialize the user_data which is already allocated automatically.

p6est_checksum()

unsigned p6est_checksum

(

p6est_t *

p6est

)

Compute the checksum for a forest.

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

Returns

Returns the checksum on processor 0 only. 0 on other processors.

p6est_coarsen_columns()

void p6est_coarsen_columns	(	p6est_t *	p6est,
		int	coarsen_recursive,
		p6est_coarsen_column_t	coarsen_fn,
		p6est_init_t	init_fn
	)

Coarsen the columns of a sheet.

Parameters

[in,out]	p6est	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 columns shall be coarsened
[in]	init_fn	Callback function to initialize the user_data which is already allocated automatically.

p6est_coarsen_layers()

void p6est_coarsen_layers	(	p6est_t *	p6est,
		int	coarsen_recursive,
		p6est_coarsen_layer_t	coarsen_fn,
		p6est_init_t	init_fn
	)

Coarsen the layers of a sheet.

Parameters

[in,out]	p6est	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 layers shall be coarsened
[in]	init_fn	Callback function to initialize the user_data which is already allocated automatically.

p6est_connectivity_new()

p6est_connectivity_t * p6est_connectivity_new	(	p4est_connectivity_t *	conn4,
		double *	top_vertices,
		double	height[3]
	)

Create a p6est_connectivity_t from a p4est_connectivity_t.

All fields are copied, so all inputs can be safey destroyed.

Parameters

[in]	conn4	the 2D connectivity
[in]	top_vertices	if NULL, then the sheet has a uniform vertical profile; otherwise, top_vertices gives the vertices of the top of the sheet; should be the same size as conn4->tree_to_vertex
[in]	height	if top_vertices == NULL, then this gives the offset from the bottom of the sheet to the top.

Returns

the 2D+1D connectivity information.

p6est_copy()

p6est_t * p6est_copy	(	p6est_t *	input,
		int	copy_data
	)

Make a deep copy of a p6est.

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.

Parameters

[in]

copy_data

If true, data are copied. If false, data_size is set to 0.

Returns

Returns a valid p6est that does not depend on the input.

p6est_destroy()

void p6est_destroy

(

p6est_t *

p6est

)

Destroy a p6est.

Note

The connectivity structure is not destroyed with the p6est.

p6est_load()

p6est_t * p6est_load	(	const char *	filename,
		sc_MPI_Comm	mpicomm,
		size_t	data_size,
		int	load_data,
		void *	user_pointer,
		p6est_connectivity_t **	connectivity
	)

Load the complete connectivity/p6est structure from disk.

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 p6est 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.

p6est_new()

p6est_t * p6est_new	(	sc_MPI_Comm	mpicomm,
		p6est_connectivity_t *	connectivity,
		size_t	data_size,
		p6est_init_t	init_fn,
		void *	user_pointer
	)

Create a new forest.

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 p6est 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 p6est 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.

p6est_new_from_p4est()

p6est_t * p6est_new_from_p4est	(	p4est_t *	p4est,
		double *	top_vertices,
		double	height[3],
		int	min_zlevel,
		size_t	data_size,
		p6est_init_t	init_fn,
		void *	user_pointer
	)

Create a new forest from an already created p4est that represents columns.

Parameters

[in]	p4est	A valid p4est. A deep copy will be created, so this can be destroyed without affectin the new p6est object.
[in]	top_vertices	the same as in p6est_conectivity_new()
[in]	height	the same as in p6est_conectivity_new()
[in]	min_zlevel	the same as in p6est_new()
[in]	data_size	the same as in p6est_new()
[in]	init_fn	the same as in p6est_new()
[in]	user_pointer	the same as in p6est_new()

Returns

This returns a valid forest. The user must destroy the connectivity for the new p6est independently.

Note

p4est->p.user_data is not retained.

p6est_partition()

p4est_gloidx_t p6est_partition	(	p6est_t *	p6est,
		p6est_weight_t	weight_fn
	)

Equally partition the forest.

The forest will be partitioned between processors where they each have an approximately equal number of quadrants.

Note that p6est->layers and p6est->global_first_layers may change during this call. Address pointers referencing these objects from before p6est_partition is called become invalid.

Parameters

[in,out]	p6est	The forest that will be partitioned.
[in]	weight_fn	A weighting function or NULL for uniform partitioning.

p6est_qcoord_to_vertex()

void p6est_qcoord_to_vertex	(	p6est_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.
[in]	x,y	Quadrant coordinates relative to treeid.
[out]	vxy	Transformed coordinates in vertex space.

p6est_refine_columns()

void p6est_refine_columns	(	p6est_t *	p6est,
		int	refine_recursive,
		p6est_refine_column_t	refine_fn,
		p6est_init_t	init_fn
	)

Refine the columns of a sheet.

Parameters

[in,out]	p6est	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 column shall be refined into smaller columns. If refine_recursive is true, refine_fn is called for every existing and newly created column. Otherwise, it is called for every existing column. 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 p6est_refine_columns_ext in p6est_extended.h and examine whether replace_fn gets called.
[in]	init_fn	Callback function to initialize the user_data of newly created layers within columns, which are already allocated. This function pointer may be NULL.

p6est_refine_layers()

void p6est_refine_layers	(	p6est_t *	p6est,
		int	refine_recursive,
		p6est_refine_layer_t	refine_fn,
		p6est_init_t	init_fn
	)

Refine the layers within the columns of a sheet.

Parameters

[in,out]	p6est	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 layer shall be refined into smaller layers. If refine_recursive is true, refine_fn is called for every existing and newly created layer. Otherwise, it is called for every existing layer. 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 p6est_refine_layers_ext in p6est_extended.h and examine whether replace_fn gets called.
[in]	init_fn	Callback function to initialize the user_data of newly created layers, which are already allocated. This function pointer may be NULL.

p6est_reset_data()

void p6est_reset_data	(	p6est_t *	p6est,
		size_t	data_size,
		p6est_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.
[in]	user_pointer	Assign to the user_pointer member of the p6est before init_fn is called the first time.

p6est_save()

void p6est_save	(	const char *	filename,
		p6est_t *	p6est,
		int	save_data
	)

Save the complete connectivity/p6est 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.

Parameters

[in]	filename	Name of the file to write.
[in]	p6est	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.

p6est_tree_get_vertices()

void p6est_tree_get_vertices	(	p6est_connectivity_t *	conn,
		p4est_topidx_t	which_tree,
		double	vertices[24]
	)

Get the vertices of the corners of a tree.

Parameters

[in]	conn	the 2D+1D connectivity structure
[in]	which_tree	a tree in the forest
[out]	vertices	the coordinates of the corners of the tree