API reference

P4est.init(log_handler, log_threshold)

Calls p4est_init if it has not already been called, otherwise do nothing. Thus, P4est.init can safely be called multiple times.

To use the default log handler and suppress most output created by default by p4est, call this function as

P4est.init(C_NULL, SC_LP_ERROR)

before calling other functions from p4est.

P4est.package_id()

Returns the value of the global variable p4est_package_id which can be used to check whether p4est has been initialized.

P4est.path_p4est_library()

Return the path of the p4est library that is used, when a system-provided library is configured via the preferences. Otherwise P4est_jll is returned, which means that the default p4est version from P4est_jll.jl is used.

P4est.path_sc_library()

Return the path of the sc library that is used, when a system-provided library is configured via the preferences. Otherwise P4est_jll is returned, which means that the default sc version from P4est_jll.jl is used.

P4est.preferences_set_correctly()

Returns false if a system-provided MPI installation is set via the MPIPreferences, but not a system-provided p4est installation. In this case, P4est.jl is not usable.

P4est.set_library_p4est!(path; force = true)

Set the path to a system-provided p4est installation. Restart the Julia session after executing this function so that the changes take effect. Calling this function is necessary when you want to use a system-provided p4est installation.

P4est.set_library_sc!(path; force = true)

Set the path to a system-provided sc installation. Restart the Julia session after executing this function so that the changes take effect. Calling this function is necessary, when you want to use a system-provided p4est installation on Windows or when you want to use another sc installation than the one that libp4est.so already links to.

P4est.uses_mpi()

Is intended to return trueif thep4estlibrary was compiled with MPI enabled. Since P4est.jl currently only supportsp4estwith MPI enabled, this may always returntrue`.

P4est.version()

Returns the version of the underlying p4est library (not of P4est.jl).

PointerWrapper(p::Ptr)

Wrap the pointer p to conveniently access the data of the underlying struct. Fields of the struct (or the struct itself) can be dereferenced for reading/writing using []. As opposed to using unsafe_load/unsafe_store on the struct directly, the [] operator only accesses the memory for the requested field, thereby avoiding to having to load/store the entire struct when accessing only a single field. This can be helpful especially when accessing data in nested structures.

Example

julia> using P4est, MPI

julia> MPI.Init()
MPI.ThreadLevel(2)

julia> connectivity = p4est_connectivity_new_brick(2, 2, 0, 0)
Ptr{p4est_connectivity} @0x000060000378b010

julia> p4est = p4est_new_ext(MPI.COMM_WORLD, connectivity, 0, 0, true, 0, C_NULL, C_NULL)
Into p4est_new with min quadrants 0 level 0 uniform 1
New p4est with 4 trees on 1 processors
Initial level 0 potential global quadrants 4 per tree 1
Done p4est_new with 4 total quadrants
Ptr{P4est.LibP4est.p4est} @0x0000600002b9d7b0

julia> p4est_pw = PointerWrapper(p4est)
PointerWrapper{P4est.LibP4est.p4est}(Ptr{P4est.LibP4est.p4est} @0x0000600002b9d7b0)

julia> p4est_pw.connectivity.num_trees[]
4

Callback function prototype to decide for coarsening.

Parameters

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

Returns

nonzero if the quadrants shall be replaced with their parent.

p4est_comm_tag

Tags for MPI messages

Tags for MPI messages

p4est_connect_type_t

Characterize a type of adjacency.

Several functions involve relationships between neighboring trees and/or quadrants, and their behavior depends on how one defines adjacency: 1) entities are adjacent if they share a face, or 2) entities are adjacent if they share a face or corner. p4est_connect_type_t is used to choose the desired behavior. This enum must fit into an int8_t.

p4est_connectivity

This structure holds the 2D inter-tree connectivity information. Identification of arbitrary faces and corners is possible.

The arrays tree_to_* are stored in z ordering. For corners the order wrt. yx is 00 01 10 11. For faces the order is -x +x -y +y. They are allocated [0][0]..[0][3]..[num_trees-1][0]..[num_trees-1][3].

The values for tree_to_face are 0..7 where ttf % 4 gives the face number and ttf / 4 the face orientation code. The orientation is 0 for edges that are aligned in z-order, and 1 for edges that are running opposite in z-order.

It is valid to specify num_vertices as 0. In this case vertices and tree_to_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num_vertices-1][0]..[num_vertices-1][2].

The corners are only stored when they connect trees. In this case tree_to_corner indexes into ctt_offset. Otherwise the tree_to_corner entry must be -1 and this corner is ignored. If num_corners == 0, tree_to_corner and corner_to_* arrays are set to NULL.

The arrays corner_to_* store a variable number of entries per corner. For corner c these are at position [ctt_offset[c]]..[ctt_offset[c+1]-1]. Their number for corner c is ctt_offset[c+1] - ctt_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner_to_* arrays is num_ctt = ctt_offset[num_corners].

The *_to_attr arrays may have arbitrary contents defined by the user.

p4est_connectivity_encode_t

Typedef for serialization method.

This structure holds the 2D inter-tree connectivity information. Identification of arbitrary faces and corners is possible.

The arrays tree_to_* are stored in z ordering. For corners the order wrt. yx is 00 01 10 11. For faces the order is -x +x -y +y. They are allocated [0][0]..[0][3]..[num_trees-1][0]..[num_trees-1][3].

The values for tree_to_face are 0..7 where ttf % 4 gives the face number and ttf / 4 the face orientation code. The orientation is 0 for edges that are aligned in z-order, and 1 for edges that are running opposite in z-order.

It is valid to specify num_vertices as 0. In this case vertices and tree_to_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num_vertices-1][0]..[num_vertices-1][2].

The corners are only stored when they connect trees. In this case tree_to_corner indexes into ctt_offset. Otherwise the tree_to_corner entry must be -1 and this corner is ignored. If num_corners == 0, tree_to_corner and corner_to_* arrays are set to NULL.

The arrays corner_to_* store a variable number of entries per corner. For corner c these are at position [ctt_offset[c]]..[ctt_offset[c+1]-1]. Their number for corner c is ctt_offset[c+1] - ctt_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner_to_* arrays is num_ctt = ctt_offset[num_corners].

The *_to_attr arrays may have arbitrary contents defined by the user.

p4est_ghost_exchange

Transient storage for asynchronous ghost exchange.

Transient storage for asynchronous ghost exchange.

p4est_ghost_t

quadrants that neighbor the local domain

Typedef for globally unique indexing of quadrants.

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

Parameters

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

p4est_inspect

Data pertaining to selecting, inspecting, and profiling algorithms. A pointer to this structure is hooked into the p4est main structure.

The balance_ranges and balance_notify* times are collected whenever an inspect structure is present in p4est.

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_iter_corner_info

The information that is available to the user-defined p4est_iter_corner_t callback.

If tree_boundary is false, the corner is on the interior of a tree. When tree_boundary is false, sides[0] contains the lowest z-order quadrant that touches the corner. When tree_boundary is true, its value is P4EST_CONNECT_FACE/CORNER depending on the location of the corner relative to the tree.

The information that is available to the user-defined p4est_iter_corner_t callback.

If tree_boundary is false, the corner is on the interior of a tree. When tree_boundary is false, sides[0] contains the lowest z-order quadrant that touches the corner. When tree_boundary is true, its value is P4EST_CONNECT_FACE/CORNER depending on the location of the corner relative to the tree.

p4est_iter_corner_side

Information about one side of a corner in the forest. If a quad is local (is_ghost is false), then its quadid indexes the tree's quadrant array; otherwise, it indexes the ghosts array. If a quadrant should be present, but it is not included in the ghost layer, then quad = NULL, is_ghost is true, and quadid = -1.

the faces field provides some additional information about the local topology: if side[i]->faces[j] == side[k]->faces[l], this indicates that there is a common face between these two sides of the corner.

Information about one side of a corner in the forest. If a quad is local (is_ghost is false), then its quadid indexes the tree's quadrant array; otherwise, it indexes the ghosts array. If a quadrant should be present, but it is not included in the ghost layer, then quad = NULL, is_ghost is true, and quadid = -1.

the faces field provides some additional information about the local topology: if side[i]->faces[j] == side[k]->faces[l], this indicates that there is a common face between these two sides of the corner.

The prototype for a function that p4est_iterate will execute wherever quadrants meet at a conformal corner

i.e. the callback will not execute on a hanging corner.

Parameters

• info:[in] information about a quadrant provided to the user
• user_data:[in,out] the user context passed to p4est_iterate()

p4est_iter_face_info

The information that is available to the user-defined p4est_iter_face_t callback.

The orientation is 0 if the face is within one tree; otherwise, it is the same as the orientation value between the two trees given in the connectivity. If the face is on the outside boundary of the forest, then there is only one side. If tree_boundary is false, the face is on the interior of a tree. When tree_boundary is false, sides[0] contains the lowest z-order quadrant that touches the face. When tree_boundary is true, its value is P4EST_CONNECT_FACE.

The information that is available to the user-defined p4est_iter_face_t callback.

The orientation is 0 if the face is within one tree; otherwise, it is the same as the orientation value between the two trees given in the connectivity. If the face is on the outside boundary of the forest, then there is only one side. If tree_boundary is false, the face is on the interior of a tree. When tree_boundary is false, sides[0] contains the lowest z-order quadrant that touches the face. When tree_boundary is true, its value is P4EST_CONNECT_FACE.

p4est_iter_face_side

Information about one side of a face in the forest.

If a quad is local (is_ghost is false), then its quadid indexes the tree's quadrant array; otherwise, it indexes the ghosts array. If the face is hanging, then the quadrants are listed in z-order. If a quadrant should be present, but it is not included in the ghost layer, then quad = NULL, is_ghost is true, and quadid = -1.

Information about one side of a face in the forest.

If a quad is local (is_ghost is false), then its quadid indexes the tree's quadrant array; otherwise, it indexes the ghosts array. If the face is hanging, then the quadrants are listed in z-order. If a quadrant should be present, but it is not included in the ghost layer, then quad = NULL, is_ghost is true, and quadid = -1.

The prototype for a function that p4est_iterate will execute wherever two quadrants share a face: the face can be a 2:1 hanging face, it does not have to be conformal.

Parameters

• info:[in] information about a quadrant provided to the user
• user_data:[in,out] the user context passed to p4est_iterate()

p4est_iter_volume_info

The information that is available to the user-defined p4est_iter_volume_t callback function.

treeid gives the index in p4est->trees of the tree to which quad belongs. quadid gives the index of quad within tree's quadrants array.

The information that is available to the user-defined p4est_iter_volume_t callback function.

treeid gives the index in p4est->trees of the tree to which quad belongs. quadid gives the index of quad within tree's quadrants array.

The prototype for a function that p4est_iterate will execute at every quadrant local to the current process.

Parameters

• info:[in] information about a quadrant provided to the user
• user_data:[in,out] the user context passed to p4est_iterate()

A datatype to handle the linear id in 2D.

p4est_lnodes_buffer

p4est_lnodes_buffer_t handles the communication of data associated with nodes.

send_buffers is an array of arrays: one buffer for each process to which the current process sends node-data. It should not be altered between a shared__begin and a shared__end call.

recv_buffers is an array of arrays that is used in lnodes_share_all_. *recv_buffers[j] corresponds with lnodes->sharers[j]: it is the same length as lnodes->sharers[j]->sharednodes. At the completion of lnodes\share_all or lnodes_share_all_end, recv_buffers[j] contains the node-data from the process lnodes->sharers[j]->rank (unless j is the current rank, in which case recv_buffers[j] is empty).

p4est_lnodes_buffer_t handles the communication of data associated with nodes.

send_buffers is an array of arrays: one buffer for each process to which the current process sends node-data. It should not be altered between a shared__begin and a shared__end call.

recv_buffers is an array of arrays that is used in lnodes_share_all_. *recv_buffers[j] corresponds with lnodes->sharers[j]: it is the same length as lnodes->sharers[j]->sharednodes. At the completion of lnodes\share_all or lnodes_share_all_end, recv_buffers[j] contains the node-data from the process lnodes->sharers[j]->rank (unless j is the current rank, in which case recv_buffers[j] is empty).

p4est_lnodes_rank

The structure stored in the sharers array.

shared_nodes is a sorted array of p4est_locidx_t that indexes into local nodes. The shared_nodes array has a contiguous (or empty) section of nodes owned by the current rank. shared_mine_offset and shared_mine_count identify this section by indexing the shared_nodes array, not the local nodes array. owned_offset and owned_count define the section of local nodes that is owned by the listed rank (the section may be empty). For the current process these coincide with those in p4est_lnodes_t.

The structure stored in the sharers array.

shared_nodes is a sorted array of p4est_locidx_t that indexes into local nodes. The shared_nodes array has a contiguous (or empty) section of nodes owned by the current rank. shared_mine_offset and shared_mine_count identify this section by indexing the shared_nodes array, not the local nodes array. owned_offset and owned_count define the section of local nodes that is owned by the listed rank (the section may be empty). For the current process these coincide with those in p4est_lnodes_t.

Store a parallel numbering of Lobatto points of a given degree > 0.

Each element has degree+1 nodes per face and vnodes = (degree+1)^2 nodes per volume. num_local_elements is the number of local quadrants in the p4est. element_nodes is of dimension vnodes * num_local_elements and lists the nodes of each element in lexicographic yx-order (x varies fastest); so for degree == 2, this is the layout of nodes:

f_3 c_2 c_3 6–-7–-8 | | f_0 3 4 5 f_1 | | 0–-1–-2 c_0 c_1 f_2

element_nodes indexes into the set of local nodes, layed out as follows: local nodes = [<––-owned_count––->|<––-nonlocal_nodes––->] = [<––––––––num_local_nodes––––––––->] nonlocal_nodes contains the globally unique numbers for independent nodes that are owned by other processes; for local nodes, the globally unique numbers are given by i + global_offset, where i is the local number. Hanging nodes are always local and don't have a global number. They index the geometrically corresponding independent nodes of a neighbor.

Whether nodes are hanging or not is decided based on the element faces. This information is encoded in face_code with one int8_t per element. If no faces are hanging, the value is zero, otherwise the face_code is interpreted by p4est_lnodes_decode.

Independent nodes can be shared by multiple MPI ranks. The owner rank of a node is the one from the lowest numbered element on the lowest numbered octree touching the node.

What is meant by touching? A quadrant is said to touch all faces/corners that are incident on it, and by extension all nodes that are contained in those faces/corners.

X +–––––-+ o | | o | | +––-+ o | p | | q | o | | | | o | | +––-+ O +–––––-+

In this example degree = 6. There are 5 nodes that live on the face between q and p, and one at each corner of that face. The face is incident on q, so q owns the nodes on the face (provided q is from a lower tree or has a lower index than p). The lower corner is incident on q, so q owns it as well. The upper corner is not incident on q, so q cannot own it.

global_owned_count contains the number of independent nodes owned by each process.

The sharers array contains items of type p4est_lnodes_rank_t that hold the ranks that own or share independent local nodes. If there are no shared nodes on this processor, it is empty. Otherwise, it is sorted by rank and the current process is included.

degree < 0 indicates that the lnodes data structure is being used to number the quadrant boundary object (faces and corners) rather than the $C^0$ Lobatto nodes:

if degree == -1, then one node is assigned per face, and no nodes are assigned per volume or per corner: this numbering can be used for low-order Raviart-Thomas elements. In this case, vnodes == 4, and the nodes are listed in face-order:

f_3 c_2 c_3 +–-3–-+ | | f_0 0 1 f_1 | | +–-2–-+ c_0 c_1 f_2

if degree == -2, then one node is assigned per face and per corner and no nodes are assigned per volume. In this case, vnodes == 8, and the nodes are listed in face-order, followed by corner-order:

f_3 c_2 c_3 6–-3–-7 | | f_0 0 1 f_1 | | 4–-2–-5 c_0 c_1 f_2

Typedef for processor-local indexing of quadrants and nodes.

p4est_mesh_face_neighbor_t

This structure can be used as the status of a face neighbor iterator. It always contains the face and subface of the neighbor to be processed.

p4est_mesh_t

This structure contains complete mesh information on a 2:1 balanced forest. It stores the locally relevant neighborhood, that is, all locally owned quadrants and one layer of adjacent ghost quadrants and their owners.

For each local quadrant, its tree number is stored in quad_to_tree. The quad_to_tree array is NULL by default and can be enabled using p4estmeshnewext. For each ghost quadrant, its owner rank is stored in ghost\to_proc. For each level, an array of local quadrant numbers is stored in quad_level. The quad_level array is NULL by default and can be enabled using p4estmeshnew_ext.

The quad_to_quad list stores one value for each local quadrant's face. This value is in 0..local_num_quadrants-1 for local quadrants, or in local_num_quadrants + (0..ghost_num_quadrants-1) for ghost quadrants.

The quad_to_face list has equally many entries that are either: 1. A value of v = 0..7 indicates one same-size neighbor. This value is decoded as v = r * 4 + nf, where nf = 0..3 is the neighbor's connecting face number and r = 0..1 is the relative orientation of the neighbor's face; see p4est_connectivity.h. 2. A value of v = 8..23 indicates a double-size neighbor. This value is decoded as v = 8 + h * 8 + r * 4 + nf, where r and nf are as above and h = 0..1 is the number of the subface. h designates the subface of the large neighbor that the quadrant touches (this is the same as the large neighbor's face corner). 3. A value of v = -8..-1 indicates two half-size neighbors. In this case the corresponding quad_to_quad index points into the quad_to_half array that stores two quadrant numbers per index, and the orientation of the smaller faces follows from 8 + v. The entries of quad_to_half encode between local and ghost quadrant in the same way as the quad_to_quad values described above. The small neighbors in quad_to_half are stored in the sequence of the face corners of this, i.e., the large quadrant.

A quadrant on the boundary of the forest sees itself and its face number.

The quad_to_corner list stores corner neighbors that are not face neighbors. On the inside of a tree, there is precisely one such neighbor per corner. In this case, its index is encoded as described above for quad_to_quad. The neighbor's matching corner number is always diagonally opposite, that is, corner number ^ 3.

On the inside of an inter-tree face, we have precisely one corner neighbor. If a corner is an inter-tree corner, then the number of corner neighbors may be any non-negative number. In both cases, the quad_to_corner value is in local_num_quadrants + local_num_ghosts + [0 .. local_num_corners - 1]. After subtracting the number of local and ghost quadrants, it indexes into corner_offset, which encodes a group of corner neighbors. Each group contains the quadrant numbers encoded as usual for quad_to_quad in corner_quad, and the corner number from the neighbor as corner_corner.

Corners with no diagonal neighbor at all are assigned the value -3. This only happens on the domain boundary, which is necessarily a tree boundary. Corner-neighbors for hanging nodes are assigned the value -1.

TODO: In case of an inter-tree corner neighbor relation in a brick-like situation (exactly one neighbor, diagonally opposite corner number), use the same encoding as for corners within a tree.

Typedef for quadrant coordinates.

p4est_quadrant

The 2D quadrant datatype

The 2D quadrant datatype

Callback function prototype to decide for refinement.

Parameters

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

Returns

nonzero if the quadrant shall be refined.

Callback function prototype to replace one set of quadrants with another.

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

If the mesh is being refined, num_outgoing will be 1 and num_incoming will be 4, and vice versa if the mesh is being coarsened.

Parameters

• num_outgoing:[in] The number of outgoing quadrants.
• outgoing:[in] The outgoing quadrants: after the callback, the user_data, if p4est->data_size is nonzero, will be destroyed.
• num_incoming:[in] The number of incoming quadrants.
• incoming:[in,out] The incoming quadrants: prior to the callback, the user_data, if p4est->datasize is nonzero, is allocated, and the [`p4estinit_t`](@ref) callback, if it has been provided, will be called.

Callback function for the top-down search through the whole forest.

Parameters

• p4est:[in] The forest to search. We recurse through the trees one after another.
• which_tree:[in] The current tree number.
• quadrant:[in] The current quadrant in the recursion. This quadrant is either a non-leaf tree branch or a leaf. If the quadrant is contained in the local partition, we know which, otherwise we don't. Let us first consider the situation when quadrant is local, which is indicated by both pfirst and plast being equal to p4est->mpirank. Then the parameter local_num is negative for non-leaves and the number of the quadrant as a leaf in local storage otherwise. Only if the quadrant is a local leaf, it points to the actual local storage and can be used to access user data etc., and the recursion terminates. The other possibility is that pfirst < plast, in which case we proceed with the recursion, or both are equal to the same remote rank, in which case the recursion terminates. Either way, the quadrant is not from local forest storage.
• pfirst:[in] The lowest processor that owns part of quadrant. Guaranteed to be non-empty.
• plast:[in] The highest processor that owns part of quadrant. Guaranteed to be non-empty.
• local_num:[in] If quadrant is a local leaf, this number is the index of the leaf in local quadrant storage. Else, this is a negative value.
• point:[in,out] User-defined representation of a point. This parameter distinguishes two uses of the callback. For each quadrant, the callback is first called with a NULL point, and if this callback returns true, once for each point tracked in this branch. The return value for a point determines whether it shall be tracked further down the branch or not, and has no effect on a local leaf. The call with a NULL point is intended to prepare quadrant-related search meta data that is common to all points, and/or to efficiently terminate the recursion for all points in the branch in one call.

Returns

If false, the recursion at quadrant terminates. If true, it continues if pfirst < plast or if they are both equal to p4est->mpirank and the recursion has not reached a leaf yet.

Callback function to query the match of a "point" with a quadrant.

This function can be called in two roles: Per-quadrant, in which case the parameter point is NULL, or per-point, possibly many times per quadrant.

Parameters

• p4est:[in] The forest to be queried.
• which_tree:[in] The tree id under consideration.
• quadrant:[in] The quadrant under consideration. This quadrant may be coarser than the quadrants that are contained in the forest (an ancestor), in which case it is a temporary variable and not part of the forest storage. Otherwise, it is a leaf and points directly into the forest storage.
• local_num:[in] If the quadrant is not a leaf, this is < 0. Otherwise it is the (non-negative) index of the quadrant relative to the processor-local storage.
• point:[in] Representation of a "point"; user-defined. If point is NULL, the callback may be used to prepare quadrant-related search meta data.

Returns

If point is NULL, true if the search confined to quadrant should be executed, false to skip it. Else, true if point may be contained in the quadrant and false otherwise; the return value has no effect on a leaf.

Callback function for the partition recursion.

Parameters

• p4est:[in] The forest to traverse. Its local quadrants are never accessed.
• which_tree:[in] The tree number under consideration.
• quadrant:[in] This quadrant is not from local forest storage, and its user data is undefined. It represents the branch of the forest in the top-down recursion.
• pfirst:[in] The lowest processor that owns part of quadrant. Guaranteed to be non-empty.
• plast:[in] The highest processor that owns part of quadrant. Guaranteed to be non-empty. If this is equal to pfirst, then the recursion will stop for quadrant's branch after this function returns.
• point:[in,out] Pointer to a user-defined point object. If called per-quadrant, this is NULL.

Returns

If false, the recursion at quadrant is terminated. If true, it continues if pfirst < plast.

This typedef is provided for backwards compatibility.

The p4est forest datatype

Typedef for counting topological entities (trees, tree vertices).

p4est_tree

The p4est tree datatype

The p4est tree datatype

Callback function prototype to calculate weights for partitioning.

Parameters

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

Returns

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

Callback function prototype to decide for horizontal coarsening.

Parameters

• columns:[in] Pointers to 4 sibling columns.

Returns

nonzero if the columns shall be replaced with their parent.

Callback function prototype to decide for vertical coarsening.

Parameters

• layers:[in] Pointers to 2 vertical sibling layers.

Returns

nonzero if the layers shall be replaced with their parent.

p6est_connectivity

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.

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.

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

Parameters

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

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.

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

Returns

nonzero if the layer shall be refined.

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

• num_outcolumns:[in] The number of columns that contain the outgoing layers: will be either 1 or 4.
• num_outlayers:[in] 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).
• outcolumns:[in] The columns of the outgoing layers
• outlayers:[in] The outgoing layers: after the callback, the user_data, if p6est->data_size is nonzero, will be destroyed.
• num_incolumns:[in] The number of columns that contain the outgoing layers: will be either 1 or 4.
• num_inlayers:[in] The number of incoming layers: will be either 1 (coarsening), 2 (vertical refinement), or 4 (horizontal refinement)
• incolumns:[in] The columns of the incoming layers
• inlayers:[in,out] The incoming layers: prior to the callback, the user_data, if p6est->datasize is nonzero, is allocated, and the [`p6estinit_t`](@ref) callback, if it has been provided, will be called.

The p6est forest datatype

Callback function prototype to calculate weights for partitioning.

Returns

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

Callback function prototype to decide for coarsening.

Parameters

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

Returns

nonzero if the quadrants shall be replaced with their parent.

p8est_connect_type_t

Characterize a type of adjacency.

Several functions involve relationships between neighboring trees and/or quadrants, and their behavior depends on how one defines adjacency: 1) entities are adjacent if they share a face, or 2) entities are adjacent if they share a face or corner, or 3) entities are adjacent if they share a face, corner or edge. p8est_connect_type_t is used to choose the desired behavior. This enum must fit into an int8_t.

p8est_connectivity

This structure holds the 3D inter-tree connectivity information. Identification of arbitrary faces, edges and corners is possible.

The arrays tree_to_* are stored in z ordering. For corners the order wrt. zyx is 000 001 010 011 100 101 110 111. For faces the order is -x +x -y +y -z +z. They are allocated [0][0]..[0][N-1]..[num_trees-1][0]..[num_trees-1][N-1]. where N is 6 for tree and face, 8 for corner, 12 for edge.

The values for tree_to_face are in 0..23 where ttf % 6 gives the face number and ttf / 6 the face orientation code. The orientation is determined as follows. Let my_face and other_face be the two face numbers of the connecting trees in 0..5. Then the first face corner of the lower of my_face and other_face connects to a face corner numbered 0..3 in the higher of my_face and other_face. The face orientation is defined as this number. If my_face == other_face, treating either of both faces as the lower one leads to the same result.

It is valid to specify num_vertices as 0. In this case vertices and tree_to_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num_vertices-1][0]..[num_vertices-1][2].

The edges are only stored when they connect trees. In this case tree_to_edge indexes into ett_offset. Otherwise the tree_to_edge entry must be -1 and this edge is ignored. If num_edges == 0, tree_to_edge and edge_to_* arrays are set to NULL.

The arrays edge_to_* store a variable number of entries per edge. For edge e these are at position [ett_offset[e]]..[ett_offset[e+1]-1]. Their number for edge e is ett_offset[e+1] - ett_offset[e]. The entries encode all trees adjacent to edge e. The size of the edge_to_* arrays is num_ett = ett_offset[num_edges]. The edge_to_edge array holds values in 0..23, where the lower 12 indicate one edge orientation and the higher 12 the opposite edge orientation.

The corners are only stored when they connect trees. In this case tree_to_corner indexes into ctt_offset. Otherwise the tree_to_corner entry must be -1 and this corner is ignored. If num_corners == 0, tree_to_corner and corner_to_* arrays are set to NULL.

The arrays corner_to_* store a variable number of entries per corner. For corner c these are at position [ctt_offset[c]]..[ctt_offset[c+1]-1]. Their number for corner c is ctt_offset[c+1] - ctt_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner_to_* arrays is num_ctt = ctt_offset[num_corners].

The *_to_attr arrays may have arbitrary contents defined by the user.

p8est_connectivity_encode_t

Typedef for serialization method.

This structure holds the 3D inter-tree connectivity information. Identification of arbitrary faces, edges and corners is possible.

The arrays tree_to_* are stored in z ordering. For corners the order wrt. zyx is 000 001 010 011 100 101 110 111. For faces the order is -x +x -y +y -z +z. They are allocated [0][0]..[0][N-1]..[num_trees-1][0]..[num_trees-1][N-1]. where N is 6 for tree and face, 8 for corner, 12 for edge.

The values for tree_to_face are in 0..23 where ttf % 6 gives the face number and ttf / 6 the face orientation code. The orientation is determined as follows. Let my_face and other_face be the two face numbers of the connecting trees in 0..5. Then the first face corner of the lower of my_face and other_face connects to a face corner numbered 0..3 in the higher of my_face and other_face. The face orientation is defined as this number. If my_face == other_face, treating either of both faces as the lower one leads to the same result.

It is valid to specify num_vertices as 0. In this case vertices and tree_to_vertex are set to NULL. Otherwise the vertex coordinates are stored in the array vertices as [0][0]..[0][2]..[num_vertices-1][0]..[num_vertices-1][2].

The edges are only stored when they connect trees. In this case tree_to_edge indexes into ett_offset. Otherwise the tree_to_edge entry must be -1 and this edge is ignored. If num_edges == 0, tree_to_edge and edge_to_* arrays are set to NULL.

The arrays edge_to_* store a variable number of entries per edge. For edge e these are at position [ett_offset[e]]..[ett_offset[e+1]-1]. Their number for edge e is ett_offset[e+1] - ett_offset[e]. The entries encode all trees adjacent to edge e. The size of the edge_to_* arrays is num_ett = ett_offset[num_edges]. The edge_to_edge array holds values in 0..23, where the lower 12 indicate one edge orientation and the higher 12 the opposite edge orientation.

The corners are only stored when they connect trees. In this case tree_to_corner indexes into ctt_offset. Otherwise the tree_to_corner entry must be -1 and this corner is ignored. If num_corners == 0, tree_to_corner and corner_to_* arrays are set to NULL.

The arrays corner_to_* store a variable number of entries per corner. For corner c these are at position [ctt_offset[c]]..[ctt_offset[c+1]-1]. Their number for corner c is ctt_offset[c+1] - ctt_offset[c]. The entries encode all trees adjacent to corner c. The size of the corner_to_* arrays is num_ctt = ctt_offset[num_corners].

The *_to_attr arrays may have arbitrary contents defined by the user.

p8est_ghost_exchange

Transient storage for asynchronous ghost exchange.

Transient storage for asynchronous ghost exchange.

p8est_ghost_t

quadrants that neighbor the local domain

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

Parameters

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

p8est_inspect

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_iter_corner_info

The information that is availalbe to the user-defined p8est_iter_corner_t callback.

If tree_boundary is false, the corner is on the interior of a tree. When tree_boundary is false, sides[0] contains the lowest z-order quadrant that touches the corner. When tree_boundary is true, its value is P8EST_CONNECT_FACE/EDGE/CORNER depending on the location of the corner relative to the tree.

The information that is availalbe to the user-defined p8est_iter_corner_t callback.

If tree_boundary is false, the corner is on the interior of a tree. When tree_boundary is false, sides[0] contains the lowest z-order quadrant that touches the corner. When tree_boundary is true, its value is P8EST_CONNECT_FACE/EDGE/CORNER depending on the location of the corner relative to the tree.

p8est_iter_corner_side

The prototype for a function that p8est_iterate will execute wherever the corner is a corner for all quadrants that touch it

i.e. the callback will not execute on a corner that sits on a hanging face or edge.

Parameters

• info:[in] information about a quadrant provided to the user
• user_data:[in,out] the user context passed to p8est_iterate()

p8est_iter_edge_info

The information about all sides of an edge in the forest. If tree_boundary is false, the edge is on the interior of a tree. When tree_boundary is false, sides[0] contains the lowest z-order quadrant that touches the edge. When tree_boundary is true, its value is P8EST_CONNECT_FACE/EDGE depending on the location of the edge relative to the tree.

The information about all sides of an edge in the forest. If tree_boundary is false, the edge is on the interior of a tree. When tree_boundary is false, sides[0] contains the lowest z-order quadrant that touches the edge. When tree_boundary is true, its value is P8EST_CONNECT_FACE/EDGE depending on the location of the edge relative to the tree.

p8est_iter_edge_side

The prototype for a function that p8est_iterate will execute wherever the edge is an edge of all quadrants that touch it i.e. the callback will not execute on an edge the sits on a hanging face.

Parameters

• info:[in] information about a quadrant provided to the user
• user_data:[in,out] the user context passed to p8est_iterate()

p8est_iter_face_info

The information that is available to the user-defined p8est_iter_face_t callback.

The orientation is 0 if the face is within one tree; otherwise, it is the same as the orientation value between the two trees given in the connectivity. If the face is on the outside of the forest, then there is only one side. If tree_boundary is false, the face is on the interior of a tree. When tree_boundary false, sides[0] contains the lowest z-order quadrant that touches the face. When tree_boundary is true, its value is P8EST_CONNECT_FACE.

The information that is available to the user-defined p8est_iter_face_t callback.

The orientation is 0 if the face is within one tree; otherwise, it is the same as the orientation value between the two trees given in the connectivity. If the face is on the outside of the forest, then there is only one side. If tree_boundary is false, the face is on the interior of a tree. When tree_boundary false, sides[0] contains the lowest z-order quadrant that touches the face. When tree_boundary is true, its value is P8EST_CONNECT_FACE.

p8est_iter_face_side

Information about one side of a face in the forest. If a quad is local (is_ghost is false), then its quadid indexes the tree's quadrant array; otherwise, it indexes the ghosts array. If the face is hanging, then the quadrants are listed in z-order. If a quadrant should be present, but it is not included in the ghost layer, then quad = NULL, is_ghost is true, and quadid = -1.

Information about one side of a face in the forest. If a quad is local (is_ghost is false), then its quadid indexes the tree's quadrant array; otherwise, it indexes the ghosts array. If the face is hanging, then the quadrants are listed in z-order. If a quadrant should be present, but it is not included in the ghost layer, then quad = NULL, is_ghost is true, and quadid = -1.

The prototype for a function that p8est_iterate() will execute wherever two quadrants share a face: the face can be a 2:1 hanging face, it does not have to be conformal.

Parameters

• info:[in] information about a quadrant provided to the user
• user_data:[in,out] the user context passed to p8est_iterate()

p8est_iter_volume_info

The information that is available to the user-defined p8est_iter_volume_t callback function.

treeid gives the index in p4est->trees of the tree to which quad belongs. quadid gives the index of quad within tree's quadrants array.

The information that is available to the user-defined p8est_iter_volume_t callback function.

treeid gives the index in p4est->trees of the tree to which quad belongs. quadid gives the index of quad within tree's quadrants array.

The prototype for a function that p8est_iterate() will execute at every quadrant local to the current process.

Parameters

• info:[in] information about a quadrant provided to the user
• user_data:[in,out] the user context passed to p8est_iterate()

A datatype to handle the linear id in 3D. We use the implementation of unsigned 128 bit integer in libsc, i.e., a struct with the members high_bits and low_bits (both uint64_t).

p8est_lnodes_buffer

p8est_lnodes_buffer_t handles the communication of data associated with nodes.

send_buffers is an array of arrays: one buffer for each process to which the current process sends node-data. It should not be altered between a shared__begin and a shared__end call.

recv_buffers is an array of arrays that is used in lnodes_share_all_. *recv_buffers[j] corresponds with lnodes->sharers[j]: it is the same length as lnodes->sharers[j]->sharednodes. At the completion of lnodes\share_all or lnodes_share_all_end, recv_buffers[j] contains the node-data from the process lnodes->sharers[j]->rank (unless j is the current rank, in which case recv_buffers[j] is empty).

p8est_lnodes_buffer_t handles the communication of data associated with nodes.

send_buffers is an array of arrays: one buffer for each process to which the current process sends node-data. It should not be altered between a shared__begin and a shared__end call.

recv_buffers is an array of arrays that is used in lnodes_share_all_. *recv_buffers[j] corresponds with lnodes->sharers[j]: it is the same length as lnodes->sharers[j]->sharednodes. At the completion of lnodes\share_all or lnodes_share_all_end, recv_buffers[j] contains the node-data from the process lnodes->sharers[j]->rank (unless j is the current rank, in which case recv_buffers[j] is empty).

p8est_lnodes_rank

The structure stored in the sharers array.

shared_nodes is a sorted array of p4est_locidx_t that indexes into local nodes. The shared_nodes array has a contiguous (or empty) section of nodes owned by the current rank. shared_mine_offset and shared_mine_count identify this section by indexing the shared_nodes array, not the local nodes array. owned_offset and owned_count define the section of local nodes that is owned by the listed rank (the section may be empty). For the current process these coincide with those in p8est_lnodes_t.

The structure stored in the sharers array.

shared_nodes is a sorted array of p4est_locidx_t that indexes into local nodes. The shared_nodes array has a contiguous (or empty) section of nodes owned by the current rank. shared_mine_offset and shared_mine_count identify this section by indexing the shared_nodes array, not the local nodes array. owned_offset and owned_count define the section of local nodes that is owned by the listed rank (the section may be empty). For the current process these coincide with those in p8est_lnodes_t.

Store a parallel numbering of Lobatto points of a given degree > 0.

Each element has degree+1 nodes per edge and vnodes = (degree+1)^3 nodes per volume. element_nodes is of dimension vnodes * num_local_elements and lists the nodes of each element in lexicographic yx-order (x varies fastest); element_nodes indexes into the set of local nodes, layed out as follows: local nodes = [<––-owned_count––->|<––-nonlocal_nodes––->] = [<––––––––num_local_nodes––––––––->] nonlocal_nodes contains the globally unique numbers for independent nodes that are owned by other processes; for local nodes, the globally unique numbers are given by i + global_offset, where i is the local number. Hanging nodes are always local and don't have a global number. They index the geometrically corresponding independent nodes of a neighbor.

Whether nodes are hanging or not is decided based on the element faces and edges. This information is encoded in face_code with one int16_t per element. If no faces or edges are hanging, the value is zero, otherwise the face_code is interpreted by p8est_lnodes_decode.

Independent nodes can be shared by multiple MPI ranks. The owner rank of a node is the one from the lowest numbered element on the lowest numbered octree touching the node.

What is meant by touching? A quadrant is said to touch all faces/edges/corners that are incident on it, and by extension all nodes that are contained in those faces/edges/corners.

X +–––––-+ x |\ \ x | \ \ . x | \ \ x X | +–––––-+ +––-+ . . | | | |\ \ X o + | | | +––-+ o . \ | p | + | q | o \ | | \| | o \| | +––-+ O +–––––-+

In this example degree = 3. There are 4 nodes that live on the face between q and p, two on each edge and one at each corner of that face. The face is incident on q, so q owns the nodes marked '.' on the face (provided q is from a lower tree or has a lower index than p). The bottom and front edges are incident on q, so q owns its nodes marked 'o' as well. The front lower corner is incident on q, so q owns its node 'O' as well. The other edges and corners are not incident on q, so q cannot own their nodes, marked 'x' and 'X'.

global_owned_count contains the number of independent nodes owned by each process.

The sharers array contains items of type p8est_lnodes_rank_t that hold the ranks that own or share independent local nodes. If there are no shared nodes on this processor, it is empty. Otherwise, it is sorted by rank and the current process is included.

degree < 0 indicates that the lnodes data structure is being used to number the quadrant boundary object (faces, edge and corners) rather than the $C^0$ Lobatto nodes:

if degree == -1, then one node is assigned per face, and no nodes are assigned per volume, per edge, or per corner: this numbering can be used for low-order Raviart-Thomas elements. In this case, vnodes == 6, and the nodes are listed in face-order.

if degree == -2, then one node is assigned per face and per edge and no nodes are assigned per volume or per corner. In this case, vnodes == 18, and the nodes are listed in face-order, followed by edge-order.

if degree == -3, then one node is assigned per face, per edge and per corner and no nodes are assigned per volume. In this case, vnodes == 26, and the nodes are listed in face-order, followed by edge-order, followed by corner-order.

p8est_mesh_face_neighbor_t

This structure can be used as the status of a face neighbor iterator. It always contains the face and subface of the neighbor to be processed.

p8est_mesh_t

This structure contains complete mesh information on a 2:1 balanced forest. It stores the locally relevant neighborhood, that is, all locally owned quadrants and one layer of adjacent ghost quadrants and their owners.

For each local quadrant, its tree number is stored in quad_to_tree. The quad_to_tree array is NULL by default and can be enabled using p8estmeshnewext. For each ghost quadrant, its owner rank is stored in ghost\to_proc. For each level, an array of local quadrant numbers is stored in quad_level. The quad_level array is NULL by default and can be enabled using p8estmeshnew_ext.

The quad_to_quad list stores one value for each local quadrant's face. This value is in 0..local_num_quadrants-1 for local quadrants, or in local_num_quadrants + (0..ghost_num_quadrants-1) for ghost quadrants.

The quad_to_face list has equally many entries that are either: 1. A value of v = 0..23 indicates one same-size neighbor. This value is decoded as v = r * 6 + nf, where nf = 0..5 is the neighbor's connecting face number and r = 0..3 is the relative orientation of the neighbor's face; see p8est_connectivity.h. 2. A value of v = 24..119 indicates a double-size neighbor. This value is decoded as v = 24 + h * 24 + r * 6 + nf, where r and nf are as above and h = 0..3 is the number of the subface. h designates the subface of the large neighbor that the quadrant touches (this is the same as the large neighbor's face corner). 3. A value of v = -24..-1 indicates four half-size neighbors. In this case the corresponding quad_to_quad index points into the quad_to_half array that stores four quadrant numbers per index, and the orientation of the smaller faces follows from 24 + v. The entries of quad_to_half encode between local and ghost quadrant in the same way as the quad_to_quad values described above. The small neighbors in quad_to_half are stored in the sequence of the face corners of this, i.e., the large quadrant.

A quadrant on the boundary of the forest sees itself and its face number.

The quad_to_edge list stores edge neighbors that are not face neighbors. On the inside of a tree, there are one or two of those depending on size. Between trees, there can be any number of same- or different-sized neighbors. For same-tree same-size neighbors, we record their number in quad_to_edge by the same convention as described for quad_to_quad above. In this case, the neighbor's matching edge number is always diagonally opposite, that is, edge number ^ 3.

For half- and double-size and all inter-tree edge neighbors, the quad_to_edge value is in local_num_quadrants + local_num_ghosts + [0 .. local_num_edges - 1]. After subtracting the number of local and ghost quadrants, it indexes into edge_offset, which encodes a group of edge neighbors. Each member of a group may be one same/double-size quadrant or two half-size quadrants; this is determined by the value of the edge_edge field as follows. 1. A value of e = 0..23 indicates one same-size neighbor. This value is encoded as e = r * 12 + ne, where ne = 0..11 is the neighbor's connecting edge number and r = 0..1 indicates an edge flip. 2. A value of e = 24..71 indicates a double-size neighbor. This value is decoded as e = 24 + h * 24 + r * 12 + ne, where r and ne are as above and h = 0..1 is the number of the subedge. h designates the subedge of the large neighbor that the quadrant touches (this is the same as the large neighbor's edge corner). 3. A value of e = -24..-1 indicates two half-size neighbors. They are represented by two consecutive entries of the edge_quad and edge_edge arrays with identical values for edge_edge. The orientation of the smaller edges follows from 24 + e. The small neighbors in edge_quad are stored in the sequence of the edge corners of this, i.e., the large quadrant.

Edges with no diagonal neighbor at all are assigned the value -3. This only happens on the domain boundary, which is necessarily a tree boundary. Edge neighbors for face-hanging nodes are assigned the value -1.

The quad_to_corner list stores corner neighbors that are not face or edge neighbors. On the inside of a tree, there is precisely one such neighbor per corner. In this case, its index is encoded as described above for quad_to_quad. The neighbor's matching corner number is always diagonally opposite, that is, corner number ^ 7.

On the inside of an inter-tree face, we have precisely one corner neighbor. If a corner is across an inter-tree edge or corner, then the number of corner neighbors may be any non-negative number. In all three cases, the quad_to_corner value is in local_num_quadrants + local_num_ghosts + [0 .. local_num_corners - 1]. After subtracting the number of local and ghost quadrants, it indexes into corner_offset, which encodes a group of corner neighbors. Each group contains the quadrant numbers encoded as usual for quad_to_quad in corner_quad, and the corner number from the neighbor as corner_corner.

Corners with no diagonal neighbor at all are assigned the value -3. This only happens on the domain boundary, which is necessarily a tree boundary. Corner-neighbors for face- and edge-hanging nodes are assigned the value -1.

TODO: In case of an inter-tree neighbor relation in a brick-like situation (one same-size neighbor, diagonally opposite edge/corner), use the same encoding as for edges/corners within a tree.

p8est_quadrant

The 3D quadrant (i.e., octant) datatype

The 3D quadrant (i.e., octant) datatype

Callback function prototype to decide for refinement.

Parameters

• p8est:[in] the forest
• which_tree:[in] the tree containing quadrant
• quadrant:[in] the quadrant that may be refined

Returns

nonzero if the quadrant shall be refined.

Callback function prototype to replace one set of quadrants with another.

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

If the mesh is being refined, num_outgoing will be 1 and num_incoming will be 8, and vice versa if the mesh is being coarsened.

Parameters

• num_outgoing:[in] The number of outgoing quadrants.
• outgoing:[in] The outgoing quadrants: after the callback, the user_data, if p8est->data_size is nonzero, will be destroyed.
• num_incoming:[in] The number of incoming quadrants.
• incoming:[in,out] The incoming quadrants: prior to the callback, the user_data, if p8est->datasize is nonzero, is allocated, and the [`p8estinit_t`](@ref) callback, if it has been provided, will be called.

Callback function for the top-down search through the whole forest.

Parameters

• p4est:[in] The forest to search. We recurse through the trees one after another.
• which_tree:[in] The current tree number.
• quadrant:[in] The current quadrant in the recursion. This quadrant is either a non-leaf tree branch or a leaf. If the quadrant is contained in the local partition, we know which, otherwise we don't. Let us first consider the situation when quadrant is local, which is indicated by both pfirst and plast being equal to p4est->mpirank. Then the parameter local_num is negative for non-leaves and the number of the quadrant as a leaf in local storage otherwise. Only if the quadrant is a local leaf, it points to the actual local storage and can be used to access user data etc., and the recursion terminates. The other possibility is that pfirst < plast, in which case we proceed with the recursion, or both are equal to the same remote rank, in which case the recursion terminates. Either way, the quadrant is not from local forest storage.
• pfirst:[in] The lowest processor that owns part of quadrant. Guaranteed to be non-empty.
• plast:[in] The highest processor that owns part of quadrant. Guaranteed to be non-empty.
• local_num:[in] If quadrant is a local leaf, this number is the index of the leaf in local quadrant storage. Else, this is a negative value.
• point:[in,out] User-defined representation of a point. This parameter distinguishes two uses of the callback. For each quadrant, the callback is first called with a NULL point, and if this callback returns true, once for each point tracked in this branch. The return value for a point determines whether it shall be tracked further down the branch or not, and has no effect on a local leaf. The call with a NULL point is intended to prepare quadrant-related search meta data that is common to all points, and/or to efficiently terminate the recursion for all points in the branch in one call.

Returns

If false, the recursion at quadrant terminates. If true, it continues if pfirst < plast or if they are both equal to p4est->mpirank and the recursion has not reached a leaf yet.

Callback function to query the match of a "point" with a quadrant.

This function can be called in two roles: Per-quadrant, in which case the parameter point is NULL, or per-point, possibly many times per quadrant.

Parameters

• p4est:[in] The forest to be queried.
• which_tree:[in] The tree id under consideration.
• quadrant:[in] The quadrant under consideration. This quadrant may be coarser than the quadrants that are contained in the forest (an ancestor), in which case it is a temporary variable and not part of the forest storage. Otherwise, it is a leaf and points directly into the forest storage.
• local_num:[in] If the quadrant is not a leaf, this is < 0. Otherwise it is the (non-negative) index of the quadrant relative to the processor-local storage.
• point:[in] Representation of a "point"; user-defined. If point is NULL, the callback may be used to prepare quadrant-related search meta data.

Returns

If point is NULL, true if the search confined to quadrant should be executed, false to skip it. Else, true if point may be contained in the quadrant and false otherwise; the return value has no effect on a leaf.

Callback function for the partition recursion.

Parameters

• p4est:[in] The forest to traverse. Its local quadrants are never accessed.
• which_tree:[in] The tree number under consideration.
• quadrant:[in] This quadrant is not from local forest storage, and its user data is undefined. It represents the branch of the forest in the top-down recursion.
• pfirst:[in] The lowest processor that owns part of quadrant. Guaranteed to be non-empty.
• plast:[in] The highest processor that owns part of quadrant. Guaranteed to be non-empty. If this is equal to pfirst, then the recursion will stop for quadrant's branch after this function returns.
• point:[in,out] Pointer to a user-defined point object. If called per-quadrant, this is NULL.

Returns

If false, the recursion at quadrant is terminated. If true, it continues if pfirst < plast.

This typedef is provided for backwards compatibility.

The p8est forest datatype

p8est_tree

The p8est tree datatype

The p8est tree datatype

Callback function prototype to calculate weights for partitioning.

Parameters

• p8est:[in] the forest
• which_tree:[in] the tree containing quadrant

Returns

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

sc_array

The sc_array object provides a dynamic array of equal-size elements. Elements are accessed by their 0-based index. Their address may change. The number of elements (== elem_count) of the array can be changed by scarrayresize and scarrayrewind. Elements can be sorted with scarraysort. If the array is sorted, it can be searched with scarraybsearch. A priority queue is implemented with pqueue_add and pqueue_pop (untested).

The sc_array object provides a dynamic array of equal-size elements. Elements are accessed by their 0-based index. Their address may change. The number of elements (== elem_count) of the array can be changed by scarrayresize and scarrayrewind. Elements can be sorted with scarraysort. If the array is sorted, it can be searched with scarraybsearch. A priority queue is implemented with pqueue_add and pqueue_pop (untested).

Function to determine the enumerable type of an object in an array.

Parameters

• array:[in] Array containing the object.
• index:[in] The location of the object.
• data:[in] Arbitrary user data.

Function to check equality of two objects.

Parameters

• u:[in] Arbitrary user data.

Returns

Returns false if *v1 is unequal *v2 and true otherwise.

sc_hash

The sc_hash implements a hash table. It uses an array which has linked lists as elements.

sc_hash_array

The sc_hash_array implements an array backed up by a hash table. This enables O(1) access for array elements.

The sc_hash_array implements an array backed up by a hash table. This enables O(1) access for array elements.

Function to call on every data item of a hash table.

Parameters

• v:[in] The address of the pointer to the current object.
• u:[in] Arbitrary user data.

Returns

Return true if the traversal should continue, false to stop.

Function to compute a hash value of an object.

Parameters

• v:[in] The object to hash.
• u:[in] Arbitrary user data.

Returns

Returns an unsigned integer.

The sc_hash implements a hash table. It uses an array which has linked lists as elements.

sc_io_encode_t

sc_io_error_t

Error values for io.

sc_io_mode_t

sc_io_sink

sc_io_source

sc_io_type_t

sc_link

The sc_link structure is one link of a linked list.

The sc_link structure is one link of a linked list.

sc_list

The sc_list object provides a linked list.

The sc_list object provides a linked list.

sc_mempool

The sc_mempool object provides a large pool of equal-size elements. The pool grows dynamically for element allocation. Elements are referenced by their address which never changes. Elements can be freed (that is, returned to the pool) and are transparently reused. If the zero_and_persist option is selected, new elements are initialized to all zeros on creation, and the contents of an element are not touched between freeing and re-returning it.

The sc_mempool object provides a large pool of equal-size elements. The pool grows dynamically for element allocation. Elements are referenced by their address which never changes. Elements can be freed (that is, returned to the pool) and are transparently reused. If the zero_and_persist option is selected, new elements are initialized to all zeros on creation, and the contents of an element are not touched between freeing and re-returning it.

sc_mstamp

A data container to create memory items of the same size. Allocations are bundled so it's fast for small memory sizes. The items created will remain valid until the container is destroyed. There is no option to return an item to the container. See scmempoolt for that purpose.

A data container to create memory items of the same size. Allocations are bundled so it's fast for small memory sizes. The items created will remain valid until the container is destroyed. There is no option to return an item to the container. See scmempoolt for that purpose.

sc_recycle_array

The sc_recycle_array object provides an array of slots that can be reused.

It keeps a list of free slots in the array which will be used for insertion while available. Otherwise, the array is grown.

The sc_recycle_array object provides an array of slots that can be reused.

It keeps a list of free slots in the array which will be used for insertion while available. Otherwise, the array is grown.

sc_uint128

An unsigned 128 bit integer represented as two uint64_t.

An unsigned 128 bit integer represented as two uint64_t.

p4est_balance(p4est_, btype, init_fn)

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

Parameters

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

Prototype

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

p4est_balance_ext(p4est_, btype, init_fn, replace_fn)

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

Parameters

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

Prototype

void p4est_balance_ext (p4est_t * p4est, p4est_connect_type_t btype, p4est_init_t init_fn, p4est_replace_t replace_fn);

p4est_balance_subtree_ext(p4est_, btype, which_tree, init_fn, replace_fn)

Prototype

void p4est_balance_subtree_ext (p4est_t * p4est, p4est_connect_type_t btype, p4est_topidx_t which_tree, p4est_init_t init_fn, p4est_replace_t replace_fn);

p4est_checksum(p4est_)

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.

Prototype

unsigned p4est_checksum (p4est_t * p4est);

p4est_checksum_partition(p4est_)

Compute a partition-dependent checksum for a forest.

Returns

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

Prototype

unsigned p4est_checksum_partition (p4est_t * p4est);

p4est_coarsen(p4est_, coarsen_recursive, coarsen_fn, init_fn)

Coarsen a forest.

Parameters

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

Prototype

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

p4est_coarsen_ext(p4est_, coarsen_recursive, callback_orphans, coarsen_fn, init_fn, replace_fn)

Coarsen a forest.

Parameters

• p4est:[in,out] The forest is changed in place.
• coarsen_recursive:[in] Boolean to decide on recursive coarsening.
• callback_orphans:[in] Boolean to enable calling coarsen_fn even on non-families. In this case, the second quadrant pointer in the argument list of the callback is NULL, subsequent pointers are undefined, and the return value is ignored. If coarsen_recursive is true, it is possible that a quadrant is called once or more as an orphan and eventually becomes part of a family. With coarsen_recursive false and callback_orphans true, it is guaranteed that every quadrant is passed exactly once into the coarsen_fn callback.
• coarsen_fn:[in] Callback function that returns true if a family of quadrants shall be coarsened.
• init_fn:[in] Callback function to initialize the user_data which is already allocated automatically.
• replace_fn:[in] Callback function that allows the user to change incoming quadrants based on the quadrants they replace.

Prototype

void p4est_coarsen_ext (p4est_t * p4est, int coarsen_recursive, int callback_orphans, p4est_coarsen_t coarsen_fn, p4est_init_t init_fn, p4est_replace_t replace_fn);

p4est_connect_type_int(btype)

Convert the p4est_connect_type_t into a number.

Parameters

• btype:[in] The balance type to convert.

Returns

Returns 1 or 2.

Prototype

int p4est_connect_type_int (p4est_connect_type_t btype);

p4est_connect_type_string(btype)

Convert the p4est_connect_type_t into a const string.

Parameters

• btype:[in] The balance type to convert.

Returns

Returns a pointer to a constant string.

Prototype

const char *p4est_connect_type_string (p4est_connect_type_t btype);

p4est_connectivity_bcast(conn_in, root, comm)

Prototype

p4est_connectivity_t *p4est_connectivity_bcast (p4est_connectivity_t * conn_in, int root, sc_MPI_Comm comm);

p4est_connectivity_complete(conn)

Internally connect a connectivity based on tree_to_vertex information. Periodicity that is not inherent in the list of vertices will be lost.

Parameters

• conn:[in,out] The connectivity needs to have proper vertices and tree_to_vertex fields. The tree_to_tree and tree_to_face fields must be allocated and satisfy p4est_connectivity_is_valid (conn) but will be overwritten. The corner fields will be freed and allocated anew.

Prototype

void p4est_connectivity_complete (p4est_connectivity_t * conn);

p4est_connectivity_deflate(conn, code)

Allocate memory and store the connectivity information there.

Parameters

• conn:[in] The connectivity structure to be exported to memory.
• code:[in] Encoding and compression method for serialization.

Returns

Newly created array that contains the information.

Prototype

sc_array_t *p4est_connectivity_deflate (p4est_connectivity_t * conn, p4est_connectivity_encode_t code);

p4est_connectivity_destroy(connectivity)

Destroy a connectivity structure. Also destroy all attributes.

Prototype

void p4est_connectivity_destroy (p4est_connectivity_t * connectivity);

p4est_connectivity_face_neighbor_corner(c, f, nf, o)

Transform a corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately.

.

Parameters

• c:[in] A corner number in 0..3.
• f:[in] A face number that touches the corner c.
• nf:[in] A neighbor face that is on the other side of .
• o:[in] The orientation between tree boundary faces f and

Returns

The number of the corner seen from the neighbor tree.

Prototype

int p4est_connectivity_face_neighbor_corner (int c, int f, int nf, int o);

p4est_connectivity_face_neighbor_face_corner(fc, f, nf, o)

Transform a face corner across one of the adjacent faces into a neighbor tree. This version expects the neighbor face and orientation separately.

.

Parameters

• fc:[in] A face corner number in 0..1.
• f:[in] A face that the face corner number fc is relative to.
• nf:[in] A neighbor face that is on the other side of .
• o:[in] The orientation between tree boundary faces f and

Returns

The face corner number relative to the neighbor's face.

Prototype

int p4est_connectivity_face_neighbor_face_corner (int fc, int f, int nf, int o);

p4est_connectivity_inflate(buffer)

Create new connectivity from a memory buffer.

Parameters

• buffer:[in] The connectivity is created from this memory buffer.

Returns

The newly created connectivity, or NULL on error.

Prototype

p4est_connectivity_t *p4est_connectivity_inflate (sc_array_t * buffer);

p4est_connectivity_is_equal(conn1, conn2)

Check two connectivity structures for equality.

Returns

Returns true if structures are equal, false otherwise.

Prototype

int p4est_connectivity_is_equal (p4est_connectivity_t * conn1, p4est_connectivity_t * conn2);

p4est_connectivity_is_equivalent(conn1, conn2)

p4est_connectivity_is_equivalent This function compares two connectivities for equivalence: it returns true if they are the same connectivity, or if they have the same topology. The definition of topological sameness is strict: there is no attempt made to determine whether permutation and/or rotation of the trees makes the connectivities equivalent.

Parameters

• conn1:[in] a valid connectivity
• conn2:[out] a valid connectivity

Prototype

int p4est_connectivity_is_equivalent (p4est_connectivity_t * conn1, p4est_connectivity_t * conn2);

p4est_connectivity_is_valid(connectivity)

Examine a connectivity structure.

Returns

Returns true if structure is valid, false otherwise.

Prototype

int p4est_connectivity_is_valid (p4est_connectivity_t * connectivity);

p4est_connectivity_join_faces(conn, tree_left, tree_right, face_left, face_right, orientation)

p4est_connectivity_join_faces This function takes an existing valid connectivity conn and modifies it by joining two tree faces that are currently boundary faces.

Parameters

• conn:[in,out] connectivity that will be altered.
• tree_left:[in] tree that will be on the left side of the joined faces.
• tree_right:[in] tree that will be on the right side of the joined faces.
• face_left:[in] face of tree_left that will be joined.
• face_right:[in] face of tree_right that will be joined.
• orientation:[in] the orientation of face_left and face_right once joined (see the description of p4est_connectivity_t to understand orientation).

Prototype

void p4est_connectivity_join_faces (p4est_connectivity_t * conn, p4est_topidx_t tree_left, p4est_topidx_t tree_right, int face_left, int face_right, int orientation);

p4est_connectivity_load(filename, bytes)

Load a connectivity structure from disk.

Parameters

• filename:[in] Name of the file to read.
• bytes:[in,out] Size in bytes of connectivity on disk or NULL.

Returns

Returns valid connectivity, or NULL on file error.

Prototype

p4est_connectivity_t *p4est_connectivity_load (const char *filename, size_t *bytes);

p4est_connectivity_memory_used(conn)

Calculate memory usage of a connectivity structure.

Parameters

• conn:[in] Connectivity structure.

Returns

Memory used in bytes.

Prototype

size_t p4est_connectivity_memory_used (p4est_connectivity_t * conn);

p4est_connectivity_new(num_vertices, num_trees, num_corners, num_ctt)

Allocate a connectivity structure. The attribute fields are initialized to NULL.

Parameters

• num_vertices:[in] Number of total vertices (i.e. geometric points).
• num_trees:[in] Number of trees in the forest.
• num_corners:[in] Number of tree-connecting corners.
• num_ctt:[in] Number of total trees in corner_to_tree array.

Returns

A connectivity structure with allocated arrays.

Prototype

p4est_connectivity_t *p4est_connectivity_new (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_corners, p4est_topidx_t num_ctt);

p4est_connectivity_new_brick(mi, ni, periodic_a, periodic_b)

A rectangular m by n array of trees with configurable periodicity. The brick is periodic in x and y if periodic_a and periodic_b are true, respectively.

Prototype

p4est_connectivity_t *p4est_connectivity_new_brick (int mi, int ni, int periodic_a, int periodic_b);

p4est_connectivity_new_byname(name)

Create connectivity structure from predefined catalogue.

Parameters

• name:[in] Invokes connectivity_new_* function. brick23 brick (2, 3, 0, 0) corner corner cubed cubed disk disk moebius moebius periodic periodic pillow pillow rotwrap rotwrap star star unit unitsquare

Returns

An initialized connectivity if name is defined, NULL else.

Prototype

p4est_connectivity_t *p4est_connectivity_new_byname (const char *name);

p4est_connectivity_new_copy(num_vertices, num_trees, num_corners, vertices, ttv, ttt, ttf, ttc, coff, ctt, ctc)

Allocate a connectivity structure and populate from constants. The attribute fields are initialized to NULL.

Parameters

• num_vertices:[in] Number of total vertices (i.e. geometric points).
• num_trees:[in] Number of trees in the forest.
• num_corners:[in] Number of tree-connecting corners.
• coff:[in] Corner-to-tree offsets (num_corners + 1 values). This must always be non-NULL; in trivial cases it is just a pointer to a p4est_topix value of 0.

Returns

The connectivity is checked for validity.

Prototype

p4est_connectivity_t *p4est_connectivity_new_copy (p4est_topidx_t num_vertices, p4est_topidx_t num_trees, p4est_topidx_t num_corners, const double *vertices, const p4est_topidx_t * ttv, const p4est_topidx_t * ttt, const int8_t * ttf, const p4est_topidx_t * ttc, const p4est_topidx_t * coff, const p4est_topidx_t * ctt, const int8_t * ctc);

p4est_connectivity_new_corner()

Create a connectivity structure for a three-tree mesh around a corner.

Prototype

p4est_connectivity_t *p4est_connectivity_new_corner (void);

p4est_connectivity_new_cubed()

Create a connectivity structure for the six sides of a unit cube. The ordering of the trees is as follows: 0 1 2 3 <– 3: axis-aligned top side 4 5. This choice has been made for maximum symmetry (see tree_to_* in .c file).

Prototype

p4est_connectivity_t *p4est_connectivity_new_cubed (void);

p4est_connectivity_new_disk(periodic_a, periodic_b)

Create a connectivity structure for a five-tree flat spherical disk. This disk can just as well be used as a square to test non-Cartesian maps. Without any mapping this connectivity covers the square [-3, 3]**2.

The ordering of the trees is as follows: 4 1 2 3 0.

The outside x faces may be identified topologically. The outside y faces may be identified topologically. Both identifications may be specified simultaneously. The general shape and periodicity are the same as those obtained with p4estconnectivitynewbrick (1, 1, periodic\a, periodic_b).

When setting periodic_a and periodic_b to false, the result is the same as that of p4estconnectivitynewdisknonperiodic.

Parameters

• periodic_a:[in] Bool to make disk periodic in x direction.
• periodic_b:[in] Bool to make disk periodic in y direction.

Returns

Initialized and usable connectivity.

Prototype

p4est_connectivity_t *p4est_connectivity_new_disk (int periodic_a, int periodic_b);

p4est_connectivity_new_disk2d()

Create a connectivity structure that maps a 2d disk.

This is a 5 trees connectivity meant to be used together with p4estgeometrynew_disk2d to map the disk.

Prototype

p4est_connectivity_t *p4est_connectivity_new_disk2d (void);

p4est_connectivity_new_disk_nonperiodic()

Create a connectivity structure for a five-tree flat spherical disk. This disk can just as well be used as a square to test non-Cartesian maps. Without any mapping this connectivity covers the square [-3, 3]**2.

Returns

Initialized and usable connectivity.

Prototype

p4est_connectivity_t *p4est_connectivity_new_disk_nonperiodic (void);

p4est_connectivity_new_icosahedron()

Create a connectivity for mapping the sphere using an icosahedron.

The regular icosadron is a polyhedron with 20 faces, each of which is an equilateral triangle. To build the p4est connectivity, we group faces 2 by 2 to from 10 quadrangles, and thus 10 trees.

This connectivity is meant to be used together with p4estgeometrynew_icosahedron to map the sphere.

The flat connectivity looks like that: Vextex numbering:

A00 A01 A02 A03 A04 / \ / \ / \ / \ / \ A05–-A06–-A07–-A08–-A09–-A10 \ / \ / \ / \ / \ / \ A11–-A12–-A13–-A14–-A15–-A16 \ / \ / \ / \ / \ / A17 A18 A19 A20 A21

Origin in A05.

Tree numbering:

0 2 4 6 8 1 3 5 7 9

Prototype

p4est_connectivity_t *p4est_connectivity_new_icosahedron ();

p4est_connectivity_new_moebius()

Create a connectivity structure for a five-tree moebius band.

Prototype

p4est_connectivity_t *p4est_connectivity_new_moebius (void);

p4est_connectivity_new_periodic()

Create a connectivity structure for an all-periodic unit square.

Prototype

p4est_connectivity_t *p4est_connectivity_new_periodic (void);

p4est_connectivity_new_pillow()

Create a connectivity structure for two trees on top of each other.

Prototype

p4est_connectivity_t *p4est_connectivity_new_pillow (void);

p4est_connectivity_new_rotwrap()

Create a connectivity structure for a periodic unit square. The left and right faces are identified, and bottom and top opposite.

Prototype

p4est_connectivity_t *p4est_connectivity_new_rotwrap (void);

p4est_connectivity_new_shell2d()

Create a connectivity structure that builds a 2d spherical shell. p8estconnectivitynew_shell

Prototype

p4est_connectivity_t *p4est_connectivity_new_shell2d (void);

p4est_connectivity_new_star()

Create a connectivity structure for a six-tree star.

Prototype

p4est_connectivity_t *p4est_connectivity_new_star (void);

p4est_connectivity_new_twotrees(l_face, r_face, orientation)

Create a connectivity structure for two trees being rotated w.r.t. each other in a user-defined way

Parameters

• l_face:[in] index of left face
• r_face:[in] index of right face
• orientation:[in] orientation of trees w.r.t. each other

Prototype

p4est_connectivity_t *p4est_connectivity_new_twotrees (int l_face, int r_face, int orientation);

p4est_connectivity_new_unitsquare()

Create a connectivity structure for the unit square.

Prototype

p4est_connectivity_t *p4est_connectivity_new_unitsquare (void);

p4est_connectivity_permute(conn, perm, is_current_to_new)

p4est_connectivity_permute Given a permutation perm of the trees in a connectivity conn, permute the trees of conn in place and update conn to match.

Parameters

• conn:[in,out] The connectivity whose trees are permuted.
• perm:[in] A permutation array, whose elements are size_t's.
• is_current_to_new:[in] if true, the jth entry of perm is the new index for the entry whose current index is j, otherwise the jth entry of perm is the current index of the tree whose index will be j after the permutation.

Prototype

void p4est_connectivity_permute (p4est_connectivity_t * conn, sc_array_t * perm, int is_current_to_new);

p4est_connectivity_read_inp(filename)

Create a p4est connectivity from an ABAQUS input file.

This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively.

A basic 2D mesh is given below. The *Node section gives the vertex number and x, y, and z components for each vertex. The *Element section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as:

4 3 +–––––––––-+ | | | | | | | | | | | | +–––––––––-+ 1 2

and in 3D they are given as:

8 7 +––––––––––-+ |\ |\ | \ | \ | \ | \ | \ | \ | 5+––––––––––-+6 | | | | +––|––––––––+ | 4\ | 3 \ | \ | \ | \ | \ | \| \| +––––––––––-+ 1 2

 *Heading
  box.inp
 *Node
 1,  -5, -5, 0
 2,   5, -5, 0
 3,   5,  5, 0
 4,  -5,  5, 0
 5,   0, -5, 0
 6,   5,  0, 0
 7,   0,  5, 0
 8,  -5,  0, 0
 9,   1, -1, 0
 10,  0,  0, 0
 11, -2,  1, 0
 *Element, type=CPS4, ELSET=Surface1
 1,  1, 10, 11, 8
 2,  3, 10, 9,  6
 3,  9, 10, 1,  5
 4,  7,  4, 8, 11
 5, 11, 10, 3,  7
 6,  2,  6, 9,  5

This function reads a mesh from filename and returns an associated p4est connectivity.

Parameters

• filename:[in] file to read the connectivity from

Returns

an allocated connectivity associated with the mesh in filename or NULL if an error occurred.

Prototype

p4est_connectivity_t *p4est_connectivity_read_inp (const char *filename);

p4est_connectivity_read_inp_stream(stream, num_vertices, num_trees, vertices, tree_to_vertex)

Read an ABAQUS input file from a file stream.

This utility function reads a basic ABAQUS file supporting element type with the prefix C2D4, CPS4, and S4 in 2D and of type C3D8 reading them as bilinear quadrilateral and trilinear hexahedral trees respectively.

A basic 2D mesh is given below. The *Node section gives the vertex number and x, y, and z components for each vertex. The *Element section gives the 4 vertices in 2D (8 vertices in 3D) of each element in counter clockwise order. So in 2D the nodes are given as:

4 3 +–––––––––-+ | | | | | | | | | | | | +–––––––––-+ 1 2

and in 3D they are given as:

8 7 +––––––––––-+ |\ |\ | \ | \ | \ | \ | \ | \ | 5+––––––––––-+6 | | | | +––|––––––––+ | 4\ | 3 \ | \ | \ | \ | \ | \| \| +––––––––––-+ 1 2

 *Heading
  box.inp
 *Node
 1,  -5, -5, 0
 2,   5, -5, 0
 3,   5,  5, 0
 4,  -5,  5, 0
 5,   0, -5, 0
 6,   5,  0, 0
 7,   0,  5, 0
 8,  -5,  0, 0
 9,   1, -1, 0
 10,  0,  0, 0
 11, -2,  1, 0
 *Element, type=CPS4, ELSET=Surface1
 1,  1, 10, 11, 8
 2,  3, 10, 9,  6
 3,  9, 10, 1,  5
 4,  7,  4, 8, 11
 5, 11, 10, 3,  7
 6,  2,  6, 9,  5

This code can be called two ways. The first, when vertex==NULL and tree_to_vertex==NULL, is used to count the number of trees and vertices in the connectivity to be generated by the .inp mesh in the stream. The second, when vertices!=NULL and tree_to_vertex!=NULL, fill vertices and tree_to_vertex. In this case num_vertices and num_trees need to be set to the maximum number of entries allocated in vertices and tree_to_vertex.

Parameters

• stream:[in,out] file stream to read the connectivity from
• num_vertices:[in,out] the number of vertices in the connectivity
• num_trees:[in,out] the number of trees in the connectivity
• vertices:[out] the list of vertices of the connectivity
• tree_to_vertex:[out] the tree_to_vertex map of the connectivity

Returns

0 if successful and nonzero if not

Prototype

int p4est_connectivity_read_inp_stream (FILE * stream, p4est_topidx_t * num_vertices, p4est_topidx_t * num_trees, double *vertices, p4est_topidx_t * tree_to_vertex);

p4est_connectivity_reduce(conn)

Removes corner information of a connectivity such that enough information is left to run p4est_connectivity_complete successfully. The reduced connectivity still passes p4est_connectivity_is_valid.

Parameters

• conn:[in,out] The connectivity to be reduced.

Prototype

void p4est_connectivity_reduce (p4est_connectivity_t * conn);

p4est_connectivity_refine(conn, num_per_edge)

Uniformly refine a connectivity. This is useful if you would like to uniformly refine by something other than a power of 2.

Parameters

• conn:[in] A valid connectivity
• num_per_edge:[in] The number of new trees in each direction. Must use no more than P4ESTOLDQMAXLEVEL bits.

Returns

a refined connectivity.

Prototype

p4est_connectivity_t *p4est_connectivity_refine (p4est_connectivity_t * conn, int num_per_edge);

p4est_connectivity_save(filename, connectivity)

Save a connectivity structure to disk.

Parameters

• filename:[in] Name of the file to write.
• connectivity:[in] Valid connectivity structure.

Returns

Returns 0 on success, nonzero on file error.

Prototype

int p4est_connectivity_save (const char *filename, p4est_connectivity_t * connectivity);

p4est_connectivity_set_attr(conn, bytes_per_tree)

Allocate or free the attribute fields in a connectivity.

Parameters

• conn:[in,out] The conn->*_to_attr fields must either be NULL or previously be allocated by this function.
• bytes_per_tree:[in] If 0, tree_to_attr is freed (being NULL is ok). If positive, requested space is allocated.

Prototype

void p4est_connectivity_set_attr (p4est_connectivity_t * conn, size_t bytes_per_tree);

p4est_connectivity_sink(conn, sink)

Write connectivity to a sink object.

Parameters

• conn:[in] The connectivity to be written.
• sink:[in,out] The connectivity is written into this sink.

Returns

0 on success, nonzero on error.

Prototype

int p4est_connectivity_sink (p4est_connectivity_t * conn, sc_io_sink_t * sink);

p4est_connectivity_source(source)

Read connectivity from a source object.

Parameters

• source:[in,out] The connectivity is read from this source.

Returns

The newly created connectivity, or NULL on error.

Prototype

p4est_connectivity_t *p4est_connectivity_source (sc_io_source_t * source);

p4est_copy(input, 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

• copy_data:[in] 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.

Prototype

p4est_t *p4est_copy (p4est_t * input, int copy_data);

p4est_copy_ext(input, copy_data, duplicate_mpicomm)

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

• copy_data:[in] If true, data are copied. If false, data_size is set to 0.
• duplicate_mpicomm:[in] If true, MPI communicator is copied.

Returns

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

Prototype

p4est_t *p4est_copy_ext (p4est_t * input, int copy_data, int duplicate_mpicomm);

p4est_destroy(p4est_)

Destroy a p4est.

Prototype

void p4est_destroy (p4est_t * p4est);

p4est_expand_face_transform(iface, nface, ftransform)

Fill an array with the axis combination of a face neighbor transform.

Parameters

• iface:[in] The number of the originating face.
• nface:[in] Encoded as nface = r * 4 + nf, where nf = 0..3 is the neigbbor's connecting face number and r = 0..1 is the relative orientation to the neighbor's face. This encoding matches p4est_connectivity_t.
• ftransform:[out] This array holds 9 integers. [0,2] The coordinate axis sequence of the origin face, the first referring to the tangential and the second to the normal. A permutation of (0, 1). [3,5] The coordinate axis sequence of the target face. [6,8] Edge reversal flag for tangential axis (boolean); face code in [0, 3] for the normal coordinate q: 0: q' = -q 1: q' = q + 1 2: q' = q - 1 3: q' = 2 - q [1,4,7] 0 (unused for compatibility with 3D).

Prototype

void p4est_expand_face_transform (int iface, int nface, int ftransform[]);

p4est_face_quadrant_exists(p4est_, ghost, treeid, q, face, hang, owner_rank)

Checks if quadrant exists in the local forest or the ghost layer.

For quadrants across tree boundaries it checks if the quadrant exists across any face, but not across corners.

Parameters

• p4est:[in] The forest in which to search for q.
• ghost:[in] The ghost layer in which to search for q.
• treeid:[in] The tree to which q belongs.
• q:[in] The quadrant that is being searched for.
• face:[in,out] On input, face id across which q was created. On output, the neighbor's face number augmented by orientation, so face is in 0..7.
• hang:[in,out] If not NULL, signals that q is bigger than the quadrant it came from. The child id of that originating quadrant is passed into hang. On output, hang holds the hanging face number of q that is in contact with its originator.
• owner_rank:[out] Filled with the rank of the owner if it is found and undefined otherwise.

Returns

Returns the local number of q if the quadrant exists in the local forest or in the ghost_layer. Otherwise, returns -2 for a domain boundary and -1 if not found.

Prototype

p4est_locidx_t p4est_face_quadrant_exists (p4est_t * p4est, p4est_ghost_t * ghost, p4est_topidx_t treeid, const p4est_quadrant_t * q, int *face, int *hang, int *owner_rank);

p4est_find_corner_transform(connectivity, itree, icorner, ci)

Fills an array with information about corner neighbors.

Parameters

• itree:[in] The number of the originating tree.
• icorner:[in] The number of the originating corner.
• ci:[in,out] A p4est_corner_info_t structure with initialized array.

Prototype

void p4est_find_corner_transform (p4est_connectivity_t * connectivity, p4est_topidx_t itree, int icorner, p4est_corner_info_t * ci);

p4est_find_face_transform(connectivity, itree, iface, ftransform)

Fill an array with the axis combinations of a tree neighbor transform.

Parameters

• itree:[in] The number of the originating tree.
• iface:[in] The number of the originating tree's face.
• ftransform:[out] This array holds 9 integers. [0,2] The coordinate axis sequence of the origin face. [3,5] The coordinate axis sequence of the target face. [6,8] Edge reverse flag for axis t; face code for axis n. [1,4,7] 0 (unused for compatibility with 3D).

Returns

The face neighbor tree if it exists, -1 otherwise.

Prototype

p4est_topidx_t p4est_find_face_transform (p4est_connectivity_t * connectivity, p4est_topidx_t itree, int iface, int ftransform[]);

p4est_find_higher_bound(array, q, guess)

Find the highest position tq in a quadrant array such that tq <= q.

Returns

Returns the id of the matching quadrant or -1 if array > q or the array is empty.

Prototype

ssize_t p4est_find_higher_bound (sc_array_t * array, const p4est_quadrant_t * q, size_t guess);

p4est_find_lower_bound(array, q, guess)

Find the lowest position tq in a quadrant array such that tq >= q.

Returns

Returns the id of the matching quadrant or -1 if array < q or the array is empty.

Prototype

ssize_t p4est_find_lower_bound (sc_array_t * array, const p4est_quadrant_t * q, size_t guess);

p4est_find_partition(num_procs, search_in, my_begin, my_end, _begin, _end)

Binary search in partition array. Given two targets my_begin and my_end, find offsets such that search\_in[begin] >= my\_begin, my\_end <= search\_in[end]. If more than one index satisfies the conditions, then the minimal index is the result. If there is no index that satisfies the conditions, then begin and end are tried to set equal such that search\_in[begin] >= my\_end. If my_begin is less or equal than the smallest value of search_in begin is set to 0 and if my_end is bigger or equal than the largest value of search_in end is set to num_procs - 1. If none of the above conditions is satisfied, the output is not well defined. We require `my_begin <= my_begin'.

Parameters

• num_procs:[in] Number of processes to get the length of search_in.
• search_in:[in] The sorted array (ascending) in that the function will search. If k indexes search_in, then 0 <= k < num\_procs.
• my_begin:[in] The first target that defines the start of the search window.
• my_end:[in] The second target that defines the end of the search window.
• begin:[in,out] The first offset such that search\_in[begin] >= my\_begin.
• end:[in,out] The second offset such that my\_end <= search\_in[end].

Prototype

void p4est_find_partition (const int num_procs, p4est_gloidx_t * search_in, p4est_gloidx_t my_begin, p4est_gloidx_t my_end, p4est_gloidx_t * begin, p4est_gloidx_t * end);

p4est_find_quadrant_cumulative(p4est_, cumulative_id, which_tree, quadrant_id)

Search a local quadrant by its cumulative number in the forest.

We perform a binary search over the processor-local trees, which means that it is advisable NOT to use this function if possible, and to try to maintain O(1) tree context information in the calling code.

Parameters

• p4est:[in] Forest to be worked with.
• cumulative_id:[in] Cumulative index over all trees of quadrant.
• which_tree:[in,out] If not NULL, the input value can be -1 or an initial guess for the quadrant's tree. An initial guess must be the index of a nonempty local tree. Output is the tree of returned quadrant.
• quadrant_id:[out] If not NULL, the number of quadrant in tree.

Returns

The identified quadrant.

Prototype

p4est_quadrant_t *p4est_find_quadrant_cumulative (p4est_t * p4est, p4est_locidx_t cumulative_id, p4est_topidx_t * which_tree, p4est_locidx_t * quadrant_id);

p4est_find_range_boundaries(lq, uq, level, faces, corners)

Find the boundary points touched by a range of quadrants.

Given two smallest quadrants, lq and uq, that mark the first and the last quadrant in a range of quadrants, determine which portions of the tree boundary the range touches.

Parameters

• lq:[in] The smallest quadrant at the start of the range: if NULL, the tree's first quadrant is taken to be the start of the range.
• uq:[in] The smallest quadrant at the end of the range: if NULL, the tree's last quadrant is taken to be the end of the range.
• level:[in] The level of the containing quadrant whose boundaries are tested: 0 if we want to test the boundaries of the whole tree.
• faces:[in,out] An array of size 4 that is filled: faces[i] is true if the range touches that face.
• corners:[in,out] An array of size 4 that is filled: corners[i] is true if the range touches that corner. faces or corners may be NULL.

Returns

Returns an int32_t encoded with the same information in faces and corners: the first (least) four bits represent the four faces, the next four bits represent the four corners.

Prototype

int32_t p4est_find_range_boundaries (p4est_quadrant_t * lq, p4est_quadrant_t * uq, int level, int faces[], int corners[]);

p4est_get_plex_data_ext(p4est_, ghost, lnodes, ctype, overlap, first_local_quad, out_points_per_dim, out_cone_sizes, out_cones, out_cone_orientations, out_vertex_coords, out_children, out_parents, out_childids, out_leaves, out_remotes, custom_numbering)

Create the data necessary to create a PETsc DMPLEX representation of a forest, as well as the accompanying lnodes and ghost layer. The forest must be at least face balanced (see p4est_balance()). See test/test_plex2.c for example usage.

All arrays should be initialized to hold sizeof (p4est_locidx_t), except for out_remotes, which should be initialized to hold (2 * sizeof (p4est_locidx_t)).

Parameters

• p4est:[in] the forest
• ghost:[out] the ghost layer
• lnodes:[out] the lnodes
• ctype:[in] the type of adjacency for the overlap
• overlap:[in] the number of layers of overlap (zero is acceptable)
• first_local_quad:[out] the local quadrants are assigned contiguous plex indices, starting with this index
• out_points_per_dim:[in,out] filled with argument for DMPlexCreateFromDAG()
• out_cone_sizes:[in,out] filled with argument for DMPlexCreateFromDAG()
• out_cones:[in,out] filled with argument for DMPlexCreateFromDAG()
• out_cone_orientations:[in,out] filled with argument for DMPlexCreateFromDAG()
• out_vertex_coords:[in,out] filled with argument for DMPlexCreateFromDAG()
• out_children:[in,out] filled with argument for DMPlexSetTree()
• out_parents:[in,out] filled with argument for DMPlexSetTree()
• out_childids:[in,out] filled with argument for DMPlexSetTree()
• out_leaves:[in,out] filled with argument for PetscSFSetGraph()
• out_remotes:[in,out] filled with argument for PetscSFSetGraph()
• custom_numbering:[in] Whether or use the default numbering (0) of DMPlex child ids or the custom (1).

Prototype

void p4est_get_plex_data_ext (p4est_t * p4est, p4est_ghost_t ** ghost, p4est_lnodes_t ** lnodes, p4est_connect_type_t ctype, int overlap, p4est_locidx_t * first_local_quad, sc_array_t * out_points_per_dim, sc_array_t * out_cone_sizes, sc_array_t * out_cones, sc_array_t * out_cone_orientations, sc_array_t * out_vertex_coords, sc_array_t * out_children, sc_array_t * out_parents, sc_array_t * out_childids, sc_array_t * out_leaves, sc_array_t * out_remotes, int custom_numbering);

p4est_ghost_bsearch(ghost, which_proc, which_tree, q)

Conduct binary search for exact match on a range of the ghost layer.

Parameters

• ghost:[in] The ghost layer.
• which_proc:[in] The owner of the searched quadrant. Can be -1.
• which_tree:[in] The tree of the searched quadrant. Can be -1.
• q:[in] Valid quadrant is searched in the ghost layer.

Returns

Offset in the ghost layer, or -1 if not found.

Prototype

ssize_t p4est_ghost_bsearch (p4est_ghost_t * ghost, int which_proc, p4est_topidx_t which_tree, const p4est_quadrant_t * q);

p4est_ghost_checksum(p4est_, ghost)

Compute the parallel checksum of a ghost layer.

Parameters

• p4est:[in] The MPI information of this p4est will be used.
• ghost:[in] A ghost layer obtained from the p4est.

Returns

Parallel checksum on rank 0, 0 otherwise.

Prototype

unsigned p4est_ghost_checksum (p4est_t * p4est, p4est_ghost_t * ghost);

p4est_ghost_contains(ghost, which_proc, which_tree, q)

Conduct binary search for ancestor on range of the ghost layer.

Parameters

• ghost:[in] The ghost layer.
• which_proc:[in] The owner of the searched quadrant. Can be -1.
• which_tree:[in] The tree of the searched quadrant. Can be -1.
• q:[in] Valid quadrant's ancestor is searched.

Returns

Offset in the ghost layer, or -1 if not found.

Prototype

ssize_t p4est_ghost_contains (p4est_ghost_t * ghost, int which_proc, p4est_topidx_t which_tree, const p4est_quadrant_t * q);

p4est_ghost_destroy(ghost)

Frees all memory used for the ghost layer.

Prototype

void p4est_ghost_destroy (p4est_ghost_t * ghost);

p4est_ghost_exchange_custom(p4est_, ghost, data_size, mirror_data, ghost_data)

Transfer data for local quadrants that are ghosts to other processors. The data size is the same for all quadrants and can be chosen arbitrarily.

Parameters

• p4est:[in] The forest used for reference.
• ghost:[in] The ghost layer used for reference.
• data_size:[in] The data size to transfer per quadrant.
• mirror_data:[in] One data pointer per mirror quadrant as input.
• ghost_data:[in,out] Pre-allocated contiguous data for all ghosts in sequence, which must hold at least data_size for each ghost.

Prototype

void p4est_ghost_exchange_custom (p4est_t * p4est, p4est_ghost_t * ghost, size_t data_size, void **mirror_data, void *ghost_data);

p4est_ghost_exchange_custom_begin(p4est_, ghost, data_size, mirror_data, ghost_data)

Begin an asynchronous ghost data exchange by posting messages. The arguments are identical to p4est_ghost_exchange_custom. The return type is always non-NULL and must be passed to p4est_ghost_exchange_custom_end to complete the exchange. The ghost data must not be accessed before completion. The mirror data can be safely discarded right after this function returns since it is copied into internal send buffers.

Parameters

• mirror_data:[in] Not required to stay alive any longer.
• ghost_data:[in,out] Must stay alive into the completion call.

Returns

Transient storage for messages in progress.

Prototype

p4est_ghost_exchange_t *p4est_ghost_exchange_custom_begin (p4est_t * p4est, p4est_ghost_t * ghost, size_t data_size, void **mirror_data, void *ghost_data);

p4est_ghost_exchange_custom_end(exc)

Complete an asynchronous ghost data exchange. This function waits for all pending MPI communications.

Parameters

• Data:[in,out] created ONLY by p4est_ghost_exchange_custom_begin. It is deallocated before this function returns.

Prototype

void p4est_ghost_exchange_custom_end (p4est_ghost_exchange_t * exc);

p4est_ghost_exchange_custom_levels(p4est_, ghost, minlevel, maxlevel, data_size, mirror_data, ghost_data)

Transfer data for local quadrants that are ghosts to other processors. The data size is the same for all quadrants and can be chosen arbitrarily. This function restricts the transfer to a range of refinement levels. The memory for quadrants outside the level range is not dereferenced.

Parameters

• p4est:[in] The forest used for reference.
• ghost:[in] The ghost layer used for reference.
• minlevel:[in] Level of the largest quads to be exchanged. Use <= 0 for no restriction.
• maxlevel:[in] Level of the smallest quads to be exchanged. Use >= P4EST_QMAXLEVEL for no restriction.
• data_size:[in] The data size to transfer per quadrant.
• mirror_data:[in] One data pointer per mirror quadrant as input.
• ghost_data:[in,out] Pre-allocated contiguous data for all ghosts in sequence, which must hold at least data_size for each ghost.

Prototype

void p4est_ghost_exchange_custom_levels (p4est_t * p4est, p4est_ghost_t * ghost, int minlevel, int maxlevel, size_t data_size, void **mirror_data, void *ghost_data);

p4est_ghost_exchange_custom_levels_begin(p4est_, ghost, minlevel, maxlevel, data_size, mirror_data, ghost_data)

Begin an asynchronous ghost data exchange by posting messages. The arguments are identical to p4est_ghost_exchange_custom_levels. The return type is always non-NULL and must be passed to p4est_ghost_exchange_custom_levels_end to complete the exchange. The ghost data must not be accessed before completion. The mirror data can be safely discarded right after this function returns since it is copied into internal send buffers.

Parameters

• mirror_data:[in] Not required to stay alive any longer.
• ghost_data:[in,out] Must stay alive into the completion call.

Returns

Transient storage for messages in progress.

Prototype

p4est_ghost_exchange_t *p4est_ghost_exchange_custom_levels_begin (p4est_t * p4est, p4est_ghost_t * ghost, int minlevel, int maxlevel, size_t data_size, void **mirror_data, void *ghost_data);

p4est_ghost_exchange_custom_levels_end(exc)

Complete an asynchronous ghost data exchange. This function waits for all pending MPI communications.

Parameters

• Data:[in,out] created ONLY by p4est_ghost_exchange_custom_levels_begin. It is deallocated before this function returns.

Prototype

void p4est_ghost_exchange_custom_levels_end (p4est_ghost_exchange_t * exc);

p4est_ghost_exchange_data(p4est_, ghost, ghost_data)

Transfer data for local quadrants that are ghosts to other processors. Send the data stored in the quadrant's user_data. This is either the pointer variable itself if p4est->datasize is 0, or the content of the referenced memory field if p4est->data\size is positive.

Parameters

• p4est:[in] The forest used for reference.
• ghost:[in] The ghost layer used for reference.
• ghost_data:[in,out] Pre-allocated contiguous data for all ghost quadrants in sequence. If p4est->data_size is 0, must at least hold sizeof (void *) bytes for each, otherwise p4est->data_size each.

Prototype

void p4est_ghost_exchange_data (p4est_t * p4est, p4est_ghost_t * ghost, void *ghost_data);

p4est_ghost_exchange_data_begin(p4est_, ghost, ghost_data)

Begin an asynchronous ghost data exchange by posting messages. The arguments are identical to p4est_ghost_exchange_data. The return type is always non-NULL and must be passed to p4est_ghost_exchange_data_end to complete the exchange. The ghost data must not be accessed before completion.

Parameters

• ghost_data:[in,out] Must stay alive into the completion call.

Returns

Transient storage for messages in progress.

Prototype

p4est_ghost_exchange_t *p4est_ghost_exchange_data_begin (p4est_t * p4est, p4est_ghost_t * ghost, void *ghost_data);

p4est_ghost_exchange_data_end(exc)

Complete an asynchronous ghost data exchange. This function waits for all pending MPI communications.

Parameters

• Data:[in,out] created ONLY by p4est_ghost_exchange_data_begin. It is deallocated before this function returns.

Prototype

void p4est_ghost_exchange_data_end (p4est_ghost_exchange_t * exc);

p4est_ghost_expand(p4est_, ghost)

Expand the size of the ghost layer and mirrors by one additional layer of adjacency.

Parameters

• p4est:[in] The forest from which the ghost layer was generated.
• ghost:[in,out] The ghost layer to be expanded.

Prototype

void p4est_ghost_expand (p4est_t * p4est, p4est_ghost_t * ghost);

p4est_ghost_expand_by_lnodes(p4est_, lnodes, ghost)

Expand the ghost layer as in p4est_ghost_expand(), but use node support to define adjacency instead of geometric adjacency.

Parameters

• p4est:[in] The forest from which the ghost layer was generated.
• lnodes:[in] The nodes to support.
• ghost:[in,out] The ghost layer to be expanded.

Prototype

void p4est_ghost_expand_by_lnodes (p4est_t * p4est, p4est_lnodes_t * lnodes, p4est_ghost_t * ghost);

p4est_ghost_is_valid(p4est_, ghost)

Examine if a ghost structure is valid. Test if within a ghost-structure the array ghosts is in p4est_quadrant_compare_piggy order. Test if local_num in piggy3 data member of the quadrants in ghosts and mirrors are in ascending order (ascending within each rank for ghost).

Test if the p4est_locidx_t arrays are in ascending order (for mirror_proc_mirrors ascending within each rank)

Parameters

• p4est:[in] the forest.
• ghost:[in] Ghost layer structure.

Returns

true if ghost is valid

Prototype

int p4est_ghost_is_valid (p4est_t * p4est, p4est_ghost_t * ghost);

p4est_ghost_memory_used(ghost)

Calculate the memory usage of the ghost layer.

Parameters

• ghost:[in] Ghost layer structure.

Returns

Memory used in bytes.

Prototype

size_t p4est_ghost_memory_used (p4est_ghost_t * ghost);

p4est_ghost_new(p4est_, btype)

Builds the ghost layer.

This will gather the quadrants from each neighboring proc to build one layer of face and corner based ghost elements around the ones they own.

Parameters

• p4est:[in] The forest for which the ghost layer will be generated.
• btype:[in] Which ghosts to include (across face, corner or full).

Returns

A fully initialized ghost layer.

Prototype

p4est_ghost_t *p4est_ghost_new (p4est_t * p4est, p4est_connect_type_t btype);

p4est_ghost_support_lnodes(p4est_, lnodes, ghost)

Expand the ghost layer to include the support of all nodes supported on the local partition.

Parameters

• p4est:[in] The forest from which the ghost layer was generated.
• lnodes:[in] The nodes to support.
• ghost:[in,out] The ghost layer to be expanded.

Prototype

void p4est_ghost_support_lnodes (p4est_t * p4est, p4est_lnodes_t * lnodes, p4est_ghost_t * ghost);

p4est_init(log_handler, log_threshold)

Registers p4est with the SC Library and sets the logging behavior. This function is optional. This function must only be called before additional threads are created. If this function is not called or called with log_handler == NULL, the default SC log handler will be used. If this function is not called or called with log_threshold == SC_LP_DEFAULT, the default SC log threshold will be used. The default SC log settings can be changed with sc_set_log_defaults ().

Prototype

void p4est_init (sc_log_handler_t log_handler, int log_threshold);

p4est_is_balanced(p4est_, btype)

Check a forest to see if it is balanced.

This function builds the ghost layer and discards it when done.

Parameters

• p4est:[in] The p4est to be tested.
• btype:[in] Balance type (face, corner or default, full).

Returns

Returns true if balanced, false otherwise.

Prototype

int p4est_is_balanced (p4est_t * p4est, p4est_connect_type_t btype);

p4est_iterate(p4est_, ghost_layer, user_data, iter_volume, iter_face, iter_corner)

Execute user supplied callbacks at every volume, face, and corner in the local forest.

p4est_iterate executes the user-supplied callback functions at every volume, face, and corner in the local forest. The ghost_layer may be NULL. The user_data pointer is not touched by p4est_iterate, but is passed to each of the callbacks. Any of the callbacks may be NULL. The callback functions are interspersed with each other, i.e. some face callbacks will occur between volume callbacks, and some corner callbacks will occur between face callbacks:

1. volume callbacks occur in the sorted Morton-index order. 2) a face callback is not executed until after the volume callbacks have been executed for the quadrants that share it. 3) a corner callback is not executed until the face callbacks have been executed for all faces that touch the corner. 4) it is not always the case that every face callback for a given quadrant is executed before any of the corner callbacks. 5) callbacks are not executed at faces or corners that only involve ghost quadrants, i.e. that are not adjacent in the local section of the forest.

Parameters

• p4est:[in] the forest
• ghost_layer:[in] optional: when not given, callbacks at the boundaries of the local partition cannot provide quadrant data about ghost quadrants: missing (p4est_quadrant_t *) pointers are set to NULL, missing indices are set to -1.
• user_data:[in,out] optional context to supply to each callback
• iter_volume:[in] callback function for every quadrant's interior
• iter_face:[in] callback function for every face between quadrants
• iter_corner:[in] callback function for every corner between quadrants

Prototype

void p4est_iterate (p4est_t * p4est, p4est_ghost_t * ghost_layer, void *user_data, p4est_iter_volume_t iter_volume, p4est_iter_face_t iter_face, p4est_iter_corner_t iter_corner);

p4est_iterate_ext(p4est_, ghost_layer, user_data, iter_volume, iter_face, iter_corner, remote)

p4est_iterate_ext adds the option remote: if this is false, then it is the same as p4est_iterate; if this is true, then corner callbacks are also called on corners for hanging faces touched by local quadrants.

Prototype

void p4est_iterate_ext (p4est_t * p4est, p4est_ghost_t * ghost_layer, void *user_data, p4est_iter_volume_t iter_volume, p4est_iter_face_t iter_face, p4est_iter_corner_t iter_corner, int remote);

p4est_lid_add(a, b, result)

Adds the uint128_t b to the uint128_t a. result == a or result == b is not allowed. a == b is allowed.

Parameters

• a:[in] A pointer to a p4est_lid_t.
• b:[in] A pointer to a p4est_lid_t.
• result:[out] A pointer to a p4est_lid_t. The sum a + b will be saved in result.

Prototype

void p4est_lid_add (const p4est_lid_t * a, const p4est_lid_t * b, p4est_lid_t * result);

p4est_lid_add_inplace(a, b)

Adds the p4est_lid_t b to the p4est_lid_t a. The result is saved in a. a == b is allowed.

Parameters

• a:[in,out] A pointer to a p4est_lid_t. a will be overwritten by a + b.
• b:[in] A pointer to a p4est_lid_t.

Prototype

void p4est_lid_add_inplace (p4est_lid_t * a, const p4est_lid_t * b);

p4est_lid_bitwise_and(a, b, result)

Calculates the bitwise and of the uint128_t a and the uint128_t b. a == result is allowed. Furthermore, a == result and/or b == result is allowed.

Parameters

• a:[in] A pointer to a p4est_lid_t.
• b:[in] A pointer to a p4est_lid_t.
• result:[out] A pointer to a p4est_lid_t. The bitwise and of a and b will be saved. in result.

Prototype

void p4est_lid_bitwise_and (const p4est_lid_t * a, const p4est_lid_t * b, p4est_lid_t * result);

p4est_lid_bitwise_and_inplace(a, b)

Calculates the bitwise and of the uint128_t a and the uint128_t b. a == b is allowed.

Parameters

• a:[in,out] A pointer to a p4est_lid_t. The bitwise and will be saved in a.
• b:[in] A pointer to a p4est_lid_t.

Prototype

void p4est_lid_bitwise_and_inplace (p4est_lid_t * a, const p4est_lid_t * b);

p4est_lid_bitwise_neg(a, result)

Calculates the bitwise negation of the uint128_t a. a == result is allowed.

Parameters

• a:[in] A pointer to a p4est_lid_t.
• result:[out] A pointer to a p4est_lid_t. The bitwise negation of a will be saved in result.

Prototype

void p4est_lid_bitwise_neg (const p4est_lid_t * a, p4est_lid_t * result);

p4est_lid_bitwise_or(a, b, result)

Calculates the bitwise or of the uint128_t a and b. a == result is allowed. Furthermore, a == result and/or b == result is allowed.

Parameters

• a:[in] A pointer to a p4est_lid_t.
• b:[in] A pointer to a p4est_lid_t.
• result:[out] A pointer to a p4est_lid_t. The bitwise or of a and b will be saved in result.

Prototype

void p4est_lid_bitwise_or (const p4est_lid_t * a, const p4est_lid_t * b, p4est_lid_t * result);

p4est_lid_bitwise_or_inplace(a, b)

Calculates the bitwise or of the uint128_t a and the uint128_t b. a == b is allowed.

Parameters

• a:[in,out] A pointer to a p4est_lid_t. The bitwise or will be saved in a.
• b:[in] A pointer to a p4est_lid_t.

Prototype

void p4est_lid_bitwise_or_inplace (p4est_lid_t * a, const p4est_lid_t * b);

p4est_lid_chk_bit(input, bit_number)

Returns the bit_number-th bit of input. This function checks a bit of an existing, initialized value.

Parameters

• input:[in] A pointer to a p4est_lid_t.
• bit_number:[in] The bit (counted from the right hand side) that is checked by logical and. Require 0 <= bit_number < 64.

Returns

True if bit is set, false if not.

Prototype

int p4est_lid_chk_bit (const p4est_lid_t * input, int bit_number);

p4est_lid_compare(a, b)

Compare the p4est_lid_t a and the p4est_lid_t b.

Parameters

• a:[in] A pointer to a p4est_lid_t.
• b:[in] A pointer to a p4est_lid_t.

Returns

Returns -1 if a < b, 1 if a > b and 0 if a == b.

Prototype

int p4est_lid_compare (const p4est_lid_t * a, const p4est_lid_t * b);

p4est_lid_copy(input, output)

Copies an initialized p4est_lid_t to a p4est_lid_t.

Parameters

• input:[in] A pointer to the p4est_lid_t that is copied.
• output:[in,out] A pointer to a p4est_lid_t. The low bits of output will be set to the low bits of input and high bits are ignored.

Prototype

void p4est_lid_copy (const p4est_lid_t * input, p4est_lid_t * output);

p4est_lid_init(input, high, low)

Initializes an unsigned 64 bit integer. high is just a a placeholder to use the same interface in 3D.

Parameters

• input:[in,out] A pointer to a p4est_lid_t that will be intialized.
• high:[in] The given high bits must be zero.
• low:[in] The given low bits to initialize input.

Prototype

void p4est_lid_init (p4est_lid_t * input, uint64_t high, uint64_t low);

p4est_lid_is_equal(a, b)

Checks if the p4est_lid_t a and the p4est_lid_t b are equal.

Parameters

• a:[in] A pointer to a p4est_lid_t.
• b:[in] A pointer to a p4est_lid_t.

Returns

Returns a true value if a and b are equal, false otherwise

Prototype

int p4est_lid_is_equal (const p4est_lid_t * a, const p4est_lid_t * b);

p4est_lid_set_bit(input, bit_number)

Sets the exponent-th bit of a to one. This function modifies an existing, initialized value.

Parameters

• input:[in,out] A pointer to a p4est_lid_t.
• bit_number:[in] The bit (counted from the right hand side) that is set to one by logical or. Require 0 <= bit_number < 64.

Prototype

void p4est_lid_set_bit (p4est_lid_t * input, int bit_number);

p4est_lid_set_one(input)

Initializes a linear index to one.

Parameters

• input:[out] A pointer to a p4est_lid_t that will be intialized.

Prototype

void p4est_lid_set_one (p4est_lid_t * input);

p4est_lid_set_uint64(input, u)

Initializes a linear index to an unsigned 64 bit integer.

Parameters

• input:[out] A pointer to a p4est_lid_t that will be intialized.

Prototype

void p4est_lid_set_uint64 (p4est_lid_t * input, uint64_t u);

p4est_lid_set_zero(input)

Initializes a linear index to zero.

Parameters

• input:[out] A pointer to a p4est_lid_t that will be intialized.

Prototype

void p4est_lid_set_zero (p4est_lid_t * input);

p4est_lid_shift_left(input, shift_count, result)

Calculates the bit left shift of uint128_t input by shift_count bits. We shift in zeros from the right. If shift_count >= 64, result is 0. All bits left from the 63th bit (counted zero based from the right hand side) drop out. input == result is allowed.

Parameters

• input:[in] A pointer to a p4est_lid_t.
• shift_count:[in] Bits to shift. shift_count >= 0.
• result:[in,out] A pointer to a p4est_lid_t. The left shifted number will be saved in result.

Prototype

void p4est_lid_shift_left (const p4est_lid_t * input, unsigned shift_count, p4est_lid_t * result);

p4est_lid_shift_right(input, shift_count, result)

Calculates the bit right shift of uint128_t input by shift_count bits. We shift in zeros from the left. If shift_count >= 64, result is 0. All bits right from the zeroth bit (counted from the right hand side) drop out. input == result is allowed.

Parameters

• input:[in] A pointer to a p4est_lid_t.
• shift_count:[in] Bits to shift. shift_count >= 0.
• result:[in,out] A pointer to a p4est_lid_t. The right shifted number will be saved in result.

Prototype

void p4est_lid_shift_right (const p4est_lid_t * input, unsigned shift_count, p4est_lid_t * result);

p4est_lid_sub(a, b, result)

Substracts the p4est_lid_t b from the p4est_lid_t a. This function assumes that the result is >= 0. result == a or result == b is not allowed. a == b is allowed.

Parameters

• a:[in] A pointer to a p4est_lid_t.
• b:[in] A pointer to a p4est_lid_t.
• result:[out] A pointer to a p4est_lid_t. The difference a - b will be saved in result.

Prototype

void p4est_lid_sub (const p4est_lid_t * a, const p4est_lid_t * b, p4est_lid_t * result);

p4est_lid_sub_inplace(a, b)

Substracts the uint128_t b from the uint128_t a. The result is saved in a. a == b is allowed. This function assumes that the result is >= 0.

Parameters

• a:[in,out] A pointer to a p4est_lid_t. a will be overwritten by a - b.
• b:[in] A pointer to a p4est_lid_t.

Prototype

void p4est_lid_sub_inplace (p4est_lid_t * a, const p4est_lid_t * b);

p4est_lnodes_buffer_destroy(buffer)

Prototype

void p4est_lnodes_buffer_destroy (p4est_lnodes_buffer_t * buffer);

p4est_lnodes_destroy(lnodes)

Prototype

void p4est_lnodes_destroy (p4est_lnodes_t * lnodes);

p4est_lnodes_new(p4est_, ghost_layer, degree)

Prototype

p4est_lnodes_t *p4est_lnodes_new (p4est_t * p4est, p4est_ghost_t * ghost_layer, int degree);

p4est_lnodes_share_all(node_data, lnodes)

Equivalent to calling p4est_lnodes_share_all_end directly after p4est_lnodes_share_all_begin. Use if there is no local work that can be done to mask the communication cost.

Returns

A fully initialized buffer that contains the received data. After processing this data, the buffer must be freed with p4est_lnodes_buffer_destroy.

Prototype

p4est_lnodes_buffer_t *p4est_lnodes_share_all (sc_array_t * node_data, p4est_lnodes_t * lnodes);

p4est_lnodes_share_all_begin(node_data, lnodes)

p4est_lnodes_share_all_begin

node_data is a user_defined array of arbitrary type, where each entry is associated with the lnodes local nodes entry of matching index. For every process that shares an entry with the current one, the value in the node_data array of that process is written into a buffer->recvbuffers entry as described above. The user can then perform some arbitrary work that requires the data from all processes that share a node (such as reduce, max, min, etc.). When the work concludes, the buffer should be destroyed with [`p4estlnodesbufferdestroy`](@ref).

Values of node_data are not guaranteed to be sent, and buffer->recvbuffer entries are not guaranteed to be received until the buffer created by [`p4estlnodesshareallbegin](@ref) is passed to [p4estlnodesshareall_end`](@ref).

Prototype

p4est_lnodes_buffer_t *p4est_lnodes_share_all_begin (sc_array_t * node_data, p4est_lnodes_t * lnodes);

p4est_lnodes_share_all_end(buffer)

Prototype

void p4est_lnodes_share_all_end (p4est_lnodes_buffer_t * buffer);

p4est_lnodes_share_owned(node_data, lnodes)

Equivalent to calling p4est_lnodes_share_owned_end directly after p4est_lnodes_share_owned_begin. Use if there is no local work that can be done to mask the communication cost.

Prototype

void p4est_lnodes_share_owned (sc_array_t * node_data, p4est_lnodes_t * lnodes);

p4est_lnodes_share_owned_begin(node_data, lnodes)

p4est_lnodes_share_owned_begin

node_data is a user-defined array of arbitrary type, where each entry is associated with the lnodes local nodes entry of matching index. For every local nodes entry that is owned by a process other than the current one, the value in the node_data array of the owning process is written directly into the node_data array of the current process. Values of node_data are not guaranteed to be sent or received until the buffer created by p4est_lnodes_share_owned_begin is passed to p4est_lnodes_share_owned_end.

To be memory neutral, the buffer created by p4est_lnodes_share_owned_begin must be destroying with p4est_lnodes_buffer_destroy (it is not destroyed by p4est_lnodes_share_owned_end).

Prototype

p4est_lnodes_buffer_t *p4est_lnodes_share_owned_begin (sc_array_t * node_data, p4est_lnodes_t * lnodes);

p4est_lnodes_share_owned_end(buffer)

Prototype

void p4est_lnodes_share_owned_end (p4est_lnodes_buffer_t * buffer);

p4est_load(filename, mpicomm, data_size, load_data, user_pointer, connectivity)

Prototype

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);

p4est_load_ext(filename, mpicomm, data_size, load_data, autopartition, broadcasthead, user_pointer, connectivity)

Prototype

p4est_t *p4est_load_ext (const char *filename, sc_MPI_Comm mpicomm, size_t data_size, int load_data, int autopartition, int broadcasthead, void *user_pointer, p4est_connectivity_t ** connectivity);

p4est_memory_used(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

• p4est:[in] Valid forest structure.

Returns

Memory used in bytes.

Prototype

size_t p4est_memory_used (p4est_t * p4est);

p4est_mesh_destroy(mesh)

Destroy a p4est_mesh structure.

Parameters

• mesh:[in] Mesh structure previously created by p4est_mesh_new.

Prototype

void p4est_mesh_destroy (p4est_mesh_t * mesh);

p4est_mesh_face_neighbor_data(mfn, ghost_data)

Get the user data for the current face neighbor.

Parameters

• mfn:[in] Internal status of the iterator.
• ghost_data:[in] Data for the ghost quadrants that has been synchronized with p4est_ghost_exchange_data.

Returns

A pointer to the user data for the current neighbor.

Prototype

void *p4est_mesh_face_neighbor_data (p4est_mesh_face_neighbor_t * mfn, void *ghost_data);

p4est_mesh_face_neighbor_init(mfn, p4est_, ghost, mesh, which_tree, quadrant)

Initialize a mesh neighbor iterator by quadrant pointer.

Parameters

• mfn:[out] A p4est_mesh_face_neighbor_t to be initialized.
• which_tree:[in] Tree of quadrant whose neighbors are looped over.
• quadrant:[in] Pointer to quadrant contained in which_tree.

Prototype

void p4est_mesh_face_neighbor_init (p4est_mesh_face_neighbor_t * mfn, p4est_t * p4est, p4est_ghost_t * ghost, p4est_mesh_t * mesh, p4est_topidx_t which_tree, p4est_quadrant_t * quadrant);

p4est_mesh_face_neighbor_init2(mfn, p4est_, ghost, mesh, which_tree, quadrant_id)

Initialize a mesh neighbor iterator by quadrant index.

Parameters

• mfn:[out] A p4est_mesh_face_neighbor_t to be initialized.
• which_tree:[in] Tree of quadrant whose neighbors are looped over.
• quadrant_id:[in] Index relative to which_tree of quadrant.

Prototype

void p4est_mesh_face_neighbor_init2 (p4est_mesh_face_neighbor_t * mfn, p4est_t * p4est, p4est_ghost_t * ghost, p4est_mesh_t * mesh, p4est_topidx_t which_tree, p4est_locidx_t quadrant_id);

p4est_mesh_face_neighbor_next(mfn, ntree, nquad, nface, nrank)

Move the iterator forward to loop around neighbors of the quadrant.

Parameters

• mfn:[in,out] Internal status of the iterator.
• ntree:[out] If not NULL, the tree number of the neighbor.
• nquad:[out] If not NULL, the quadrant number within tree. For ghosts instead the number in ghost layer.
• nface:[out] If not NULL, neighbor's face as in p4est_mesh_t.
• nrank:[out] If not NULL, the owner process of the neighbor.

Returns

Either a real quadrant or one from the ghost layer. Returns NULL when the iterator is done.

Prototype

p4est_quadrant_t *p4est_mesh_face_neighbor_next (p4est_mesh_face_neighbor_t * mfn, p4est_topidx_t * ntree, p4est_locidx_t * nquad, int *nface, int *nrank);

p4est_mesh_get_neighbors(p4est_, ghost, mesh, curr_quad_id, direction, neighboring_quads, neighboring_encs, neighboring_qids)

Lookup neighboring quads of quadrant in a specific direction.

Parameters

• p4est:[in] Forest to be worked with.
• ghost:[in] Ghost layer.
• mesh:[in] Mesh structure.
• curr_quad_id:[in] Process-local id of current quad.
• direction:[in] Direction i in which to look for adjacent quadrants is encoded as follows: 0 .. 3 neighbor(-s) across face i, 4 .. 7 neighbor(-s) across corner i-4. TODO: Allow any combination of empty output arrays.
• neighboring_quads:[out] Array containing neighboring quad(-s). Needs to be empty on input, size of p4est_quadrant_t *. May be NULL, then neighboring_qids must not be NULL.
• neighboring_qids:[out] Array containing quadrant ids for neighboring quadrants. May be NULL, then no neighboring qids are collected. If non-NULL the array needs to be empty and will contain int. CAUTION: Note, that the encodings differ from the encodings saved in the mesh. TODO: Encodings are the same as in p4est_mesh for all quadrants. TODO: Ghosts can be encoded by returning the quad_to_quad convention in qid. For ghost quadrants, we add -300 to the values in p4est_mesh. This means that values below -100 belong to ghosts, values above to locals. Positive values are for local quadrants, negative values indicate ghost quadrants. Faces: 1 .. 8 => same size neighbor (r * 4 + nf) + 1; nf = 0 .. 3 face index; r = 0 .. 1 relative orientation 9 .. 24 => double size neighbor 9 + h * 8 + r * 4 + nf; h = 0 .. 1 number of the subface; r, nf as above 25 .. 32 => half-size neighbors 25 + r * 4 + nf; r, nf as above Corners: 1 .. 4 => size not encoded for corners nc + 1; nc = 0 .. 3 corner index
• neighboring_encs:[out] Array containing encodings for neighboring quads. Needs to be empty, contains int.

Prototype

p4est_locidx_t p4est_mesh_get_neighbors (p4est_t * p4est, p4est_ghost_t * ghost, p4est_mesh_t * mesh, p4est_locidx_t curr_quad_id, p4est_locidx_t direction, sc_array_t * neighboring_quads, sc_array_t * neighboring_encs, sc_array_t * neighboring_qids);

p4est_mesh_get_quadrant(p4est_, mesh, qid)

Access a process-local quadrant inside a forest. Needs a mesh with populated quad_to_tree array. This is a special case of p4estmeshquadrant_cumulative.

Parameters

• p4est:[in] The forest.
• mesh:[in] The mesh.
• qid:[in] Process-local id of the quadrant (cumulative over trees).

Returns

A pointer to the requested quadrant.

Prototype

p4est_quadrant_t *p4est_mesh_get_quadrant (p4est_t * p4est, p4est_mesh_t * mesh, p4est_locidx_t qid);

p4est_mesh_memory_used(mesh)

Calculate the memory usage of the mesh structure.

Parameters

• mesh:[in] Mesh structure.

Returns

Memory used in bytes.

Prototype

size_t p4est_mesh_memory_used (p4est_mesh_t * mesh);

p4est_mesh_new(p4est_, ghost, btype)

Create a p4est_mesh structure. This function does not populate the quad_to_tree and quad_level fields. To populate them, use p4estmeshnew_ext.

Parameters

• p4est:[in] A forest that is fully 2:1 balanced.
• ghost:[in] The ghost layer created from the provided p4est.
• btype:[in] Determines the highest codimension of neighbors.

Returns

A fully allocated mesh structure.

Prototype

p4est_mesh_t *p4est_mesh_new (p4est_t * p4est, p4est_ghost_t * ghost, p4est_connect_type_t btype);

p4est_mesh_new_ext(p4est_, ghost, compute_tree_index, compute_level_lists, btype)

Create a new mesh.

Parameters

• p4est:[in] A forest that is fully 2:1 balanced.
• ghost:[in] The ghost layer created from the provided p4est.
• compute_tree_index:[in] Boolean to decide whether to allocate and compute the quad_to_tree list.
• compute_level_lists:[in] Boolean to decide whether to compute the level lists in quad_level.
• btype:[in] Currently ignored, only face neighbors are stored.

Returns

A fully allocated mesh structure.

Prototype

p4est_mesh_t *p4est_mesh_new_ext (p4est_t * p4est, p4est_ghost_t * ghost, int compute_tree_index, int compute_level_lists, p4est_connect_type_t btype);

p4est_mesh_quadrant_cumulative(p4est_, mesh, cumulative_id, which_tree, quadrant_id)

Find a quadrant based on its cumulative number in the local forest. If the quad_to_tree field of the mesh structure exists, this is O(1). Otherwise, we perform a binary search over the processor-local trees.

Parameters

• p4est:[in] Forest to be worked with.
• mesh:[in] A mesh derived from the forest.
• cumulative_id:[in] Cumulative index over all trees of quadrant. Must refer to a local (non-ghost) quadrant.
• which_tree:[in,out] If not NULL, the input value can be -1 or an initial guess for the quadrant's tree and output is the tree of returned quadrant.
• quadrant_id:[out] If not NULL, the number of quadrant in tree.

Returns

The identified quadrant.

Prototype

p4est_quadrant_t *p4est_mesh_quadrant_cumulative (p4est_t * p4est, p4est_mesh_t * mesh, p4est_locidx_t cumulative_id, p4est_topidx_t * which_tree, p4est_locidx_t * quadrant_id);

p4est_new(mpicomm, connectivity, data_size, init_fn, user_pointer)

Prototype

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

p4est_new_ext(mpicomm, connectivity, min_quadrants, min_level, fill_uniform, data_size, init_fn, user_pointer)

Prototype

p4est_t *p4est_new_ext (sc_MPI_Comm mpicomm, p4est_connectivity_t * connectivity, p4est_locidx_t min_quadrants, int min_level, int fill_uniform, size_t data_size, p4est_init_t init_fn, void *user_pointer);

p4est_partition(p4est_, allow_for_coarsening, 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

• p4est:[in,out] The forest that will be partitioned.
• allow_for_coarsening:[in] Slightly modify partition such that quadrant families are not split between ranks.
• weight_fn:[in] 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.

Prototype

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

p4est_partition_ext(p4est_, partition_for_coarsening, weight_fn)

Repartition the forest.

The forest is partitioned between processors such that each processor has an approximately equal number of quadrants (or weight).

Parameters

• p4est:[in,out] The forest that will be partitioned.
• partition_for_coarsening:[in] If true, the partition is modified to allow one level of coarsening.
• weight_fn:[in] A weighting function or NULL for uniform partitioning. 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.

Returns

The global number of shipped quadrants

Prototype

p4est_gloidx_t p4est_partition_ext (p4est_t * p4est, int partition_for_coarsening, p4est_weight_t weight_fn);

p4est_partition_for_coarsening(p4est_, num_quadrants_in_proc)

Correct partition to allow one level of coarsening.

Parameters

• p4est:[in] forest whose partition is corrected
• num_quadrants_in_proc:[in,out] partition that will be corrected

Returns

absolute number of moved quadrants

Prototype

p4est_gloidx_t p4est_partition_for_coarsening (p4est_t * p4est, p4est_locidx_t * num_quadrants_in_proc);

p4est_partition_lnodes(p4est_, ghost, degree, partition_for_coarsening)

Partition using weights based on the number of nodes assigned to each element in lnodes

Parameters

• p4est:[in,out] the forest to be repartitioned
• ghost:[in] the ghost layer
• degree:[in] the degree that would be passed to p4est_lnodes_new()
• partition_for_coarsening:[in] whether the partition should allow coarsening (i.e. group siblings who might merge)

Prototype

void p4est_partition_lnodes (p4est_t * p4est, p4est_ghost_t * ghost, int degree, int partition_for_coarsening);

p4est_partition_lnodes_detailed(p4est_, ghost, nodes_per_volume, nodes_per_face, nodes_per_corner, partition_for_coarsening)

Partition using weights that are broken down by where they reside: in volumes, on faces, or on corners.

Prototype

void p4est_partition_lnodes_detailed (p4est_t * p4est, p4est_ghost_t * ghost, int nodes_per_volume, int nodes_per_face, int nodes_per_corner, int partition_for_coarsening);

p4est_partition_to_p6est_partition(p6est_, num_columns_in_proc, num_layers_in_proc)

Prototype

void p4est_partition_to_p6est_partition (p6est_t * p6est, p4est_locidx_t * num_columns_in_proc, p4est_locidx_t * num_layers_in_proc);

p4est_qcoord_to_vertex(connectivity, treeid, x, y, vxyz)

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

Parameters

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

Prototype

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

p4est_quadrant_exists(p4est_, ghost, treeid, q, exists_arr, rproc_arr, rquad_arr)

Checks if quadrant exists in the local forest or the ghost layer.

For quadrants across tree corners it checks if the quadrant exists in any of the corner neighbors, thus it can execute multiple queries.

Parameters

• p4est:[in] The forest in which to search for q
• ghost:[in] The ghost layer in which to search for q
• treeid:[in] The tree to which q belongs (can be extended).
• q:[in] The quadrant that is being searched for.
• exists_arr:[in,out] Must exist and be of of elem_size = sizeof (int) for inter-tree corner cases. Is resized by this function to one entry for each corner search and set to true/false depending on its existence in the local forest or ghost_layer.
• rproc_arr:[in,out] If not NULL is filled with one rank per query.
• rquad_arr:[in,out] If not NULL is filled with one quadrant per query. Its piggy3 member is defined as well.

Returns

true if the quadrant exists in the local forest or in the ghost_layer, and false if doesn't exist in either.

Prototype

int p4est_quadrant_exists (p4est_t * p4est, p4est_ghost_t * ghost, p4est_topidx_t treeid, const p4est_quadrant_t * q, sc_array_t * exists_arr, sc_array_t * rproc_arr, sc_array_t * rquad_arr);

p4est_quadrant_find_owner(p4est_, treeid, face, q)

Gets the processor id of a quadrant's owner. The quadrant can lie outside of a tree across faces (and only faces).

Parameters

• p4est:[in] The forest in which to search for a quadrant.
• treeid:[in] The tree to which the quadrant belongs.
• face:[in] Supply a face direction if known, or -1 otherwise.
• q:[in] The quadrant that is being searched for.

Returns

Processor id of the owner or -1 if the quadrant lies outside of the mesh.

Prototype

int p4est_quadrant_find_owner (p4est_t * p4est, p4est_topidx_t treeid, int face, const p4est_quadrant_t * q);

p4est_quadrant_linear_id_ext128(quadrant, level, id)

Computes the linear position as p4est_lid_t of a quadrant in a uniform grid. The grid and quadrant levels need not coincide. If they do, this is the inverse of p4estquadrantset_morton.

Parameters

• quadrant:[in] Quadrant whose linear index will be computed. If the quadrant is smaller than the grid (has a higher quadrant->level), the result is computed from its ancestor at the grid's level. If the quadrant has a smaller level than the grid (it is bigger than a grid cell), the grid cell sharing its lower left corner is used as reference.
• level:[in] The level of the regular grid compared to which the linear position is to be computed.
• id:[in,out] A pointer to an allocated or static p4est_lid_t. id will be the linear position of this quadrant on a uniform grid.

Prototype

void p4est_quadrant_linear_id_ext128 (const p4est_quadrant_t * quadrant, int level, p4est_lid_t * id);

p4est_quadrant_set_morton_ext128(quadrant, level, id)

Set quadrant Morton indices based on linear position given as p4est_lid_t in uniform grid. This is the inverse operation of p4estquadrantlinear_id.

Parameters

• quadrant:[in,out] Quadrant whose Morton indices will be set.
• level:[in] Level of the grid and of the resulting quadrant.
• id:[in] Linear index of the quadrant on a uniform grid.

Prototype

void p4est_quadrant_set_morton_ext128 (p4est_quadrant_t * quadrant, int level, const p4est_lid_t * id);

p4est_refine(p4est_, refine_recursive, refine_fn, init_fn)

Refine a forest.

Parameters

• p4est:[in,out] The forest is changed in place.
• refine_recursive:[in] Boolean to decide on recursive refinement.
• refine_fn:[in] 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.
• init_fn:[in] Callback function to initialize the user_data of newly created quadrants, which is already allocated. This function pointer may be NULL.

Prototype

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

p4est_refine_ext(p4est_, refine_recursive, maxlevel, refine_fn, init_fn, replace_fn)

Refine a forest with a bounded refinement level and a replace option.

Parameters

• p4est:[in,out] The forest is changed in place.
• refine_recursive:[in] Boolean to decide on recursive refinement.
• maxlevel:[in] Maximum allowed refinement level (inclusive). If this is negative the level is restricted only by the compile-time constant QMAXLEVEL in p4est.h.
• refine_fn:[in] 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 or replace_fn gets called.
• init_fn:[in] Callback function to initialize the user_data for newly created quadrants, which is guaranteed to be allocated. This function pointer may be NULL.
• replace_fn:[in] Callback function that allows the user to change incoming quadrants based on the quadrants they replace; may be NULL.

Prototype

void p4est_refine_ext (p4est_t * p4est, int refine_recursive, int maxlevel, p4est_refine_t refine_fn, p4est_init_t init_fn, p4est_replace_t replace_fn);

p4est_reset_data(p4est_, data_size, init_fn, 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

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

Prototype

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

p4est_revision(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

• p8est:[in] The forest must be valid.

Returns

Non-negative number.

Prototype

long p4est_revision (p4est_t * p4est);

p4est_save(filename, p4est_, 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

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

Prototype

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

p4est_save_ext(filename, p4est_, save_data, save_partition)

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. See p4est_load_ext for information on the autopartition parameter.

Parameters

• filename:[in] Name of the file to write.
• p4est:[in] Valid forest structure.
• save_data:[in] If true, the element data is saved. Otherwise, a data size of 0 is saved.
• save_partition:[in] If false, save file as if 1 core was used. If true, save core count and partition. Advantage: Partition can be recovered on loading with same mpisize and autopartition false. Disadvantage: Makes the file depend on mpisize. Either way the file can be loaded with autopartition true.

Prototype

void p4est_save_ext (const char *filename, p4est_t * p4est, int save_data, int save_partition);

p4est_search(p4est_, quadrant_fn, point_fn, points)

This function is provided for backwards compatibility. We call p4estsearchlocal with call_post = 0.

Prototype

void p4est_search (p4est_t * p4est, p4est_search_query_t quadrant_fn, p4est_search_query_t point_fn, sc_array_t * points);

p4est_search_all(p4est_, call_post, quadrant_fn, point_fn, points)

Perform a top-down search on the whole forest.

This function combines the functionality of p4estsearchlocal and p4estsearchpartition; their documentation applies for the most part.

The recursion proceeds from the root quadrant of each tree until (a) we encounter a remote quadrant that covers only one processor, or (b) we encounter a local leaf quadrant. In other words, we proceed with the recursion into a quadrant's children if (a) the quadrant is split between two or more processors, no matter whether one of them is the calling processor or not, or (b) if the quadrant is on the local processor but we have not reached a leaf yet.

The search can track one or more points, which are abstract placeholders. They are matched against the quadrants traversed using a callback function. The result of the callback function can be used to stop a recursion early. The user determines how a point is interpreted, we only pass it around.

Note that in the remote case (a), we may terminate the recursion even if the quadrant is not a leaf, which we have no means of knowing. Still, this case is sufficient to determine the processor ownership of a point.

Parameters

• p4est:[in] The forest to be searched.
• call_post:[in] If true, call quadrant callback both pre and post.
• quadrant_fn:[in] Executed once for each quadrant that is entered. If the callback returns false, this quadrant and its descendants are excluded from the search, and the points in this branch are not queried further. Its point argument is always NULL. Callback may be NULL in which case it is ignored.
• point_fn:[in] Executed once for each point that is relevant for a quadrant of the search. If it returns true, the point is tracked further down that branch, else it is discarded from the queries for the children. If points is not NULL, this callback must be not NULL. If points is NULL, it is not called.
• points:[in] User-defined array of points. We do not interpret a point, just pass it into the callbacks. If NULL, only the quadrant_fn callback is executed. If that is NULL, the whole function noops. If not NULL, the point_fn is called on its members during the search.

Prototype

void p4est_search_all (p4est_t * p4est, int call_post, p4est_search_all_t quadrant_fn, p4est_search_all_t point_fn, sc_array_t * points);

p4est_search_local(p4est_, call_post, quadrant_fn, point_fn, points)

Search through the local part of a forest. The search is especially efficient if multiple targets, called "points" below, are searched for simultaneously.

The search runs over all local quadrants and proceeds recursively top-down. For each tree, it may start at the root of that tree, or further down at the root of the subtree that contains all of the tree's local quadrants. Likewise, some intermediate levels in the recursion may be skipped if the processor-local part is contained in a single deeper subtree. The outer loop is thus a depth-first, processor-local forest traversal. Each quadrant in that loop either is a leaf, or a (direct or indirect) strict ancestor of a leaf. On entering a new quadrant, a user-provided quadrant-callback is executed.

As a convenience, the user may provide anonymous "points" that are tracked down the forest. This way one search call may be used for multiple targets. The set of points that potentially matches a given quadrant diminishes from the root down to the leaves: For each quadrant, an inner loop over the potentially matching points executes a point-callback for each candidate that determines whether the point may be a match. If not, it is discarded in the current branch, otherwise it is passed to the next deeper level. The callback is allowed to return true for the same point and more than one quadrant; in this case more than one matching quadrant may be identified. The callback is also allowed to return false for all children of a quadrant that it returned true for earlier. If the point callback returns false for all points relevant to a quadrant, the recursion stops. The points can really be anything, p4est does not perform any interpretation, just passes the pointer along to the callback function.

If points are present and the first quadrant callback returned true, we execute it a second time after calling the point callback for all current points. This can be used to gather and postprocess information about the points more easily. If it returns false, the recursion stops.

If the points are a NULL array, they are ignored and the recursion proceeds by querying the per-quadrant callback. If the points are not NULL but an empty array, the recursion will stop immediately!

Parameters

• p4est:[in] The forest to be searched.
• call_post:[in] If true, call quadrant callback both pre and post.
• quadrant_fn:[in] Executed once when a quadrant is entered, and once when it is left (the second time only if points are present and the first call returned true). This quadrant is always local, if not completely then at least one descendant of it. If the callback returns false, this quadrant and its descendants are excluded from the search recursion. Its point argument is always NULL. Callback may be NULL in which case it is ignored.
• point_fn:[in] If points is not NULL, must be not NULL. Shall return true for any possible matching point. If points is NULL, this callback is ignored.
• points:[in] User-defined array of "points". If NULL, only the quadrant_fn callback is executed. If that is NULL, this function noops. If not NULL, the point_fn is called on its members during the search.

Prototype

void p4est_search_local (p4est_t * p4est, int call_post, p4est_search_local_t quadrant_fn, p4est_search_local_t point_fn, sc_array_t * points);

p4est_search_partition(p4est_, call_post, quadrant_fn, point_fn, points)

Traverse the global partition top-down. We proceed top-down through the partition, identically on all processors except for the results of two user-provided callbacks. The recursion will only go down branches that are split between multiple processors. The callback functions can be used to stop a branch recursion even for split branches. This function offers the option to search for arbitrary user-defined points analogously to p4estsearchlocal.

Parameters

• p4est:[in] The forest to traverse. Its local quadrants are never accessed.
• call_post:[in] If true, call quadrant callback both pre and post.
• quadrant_fn:[in] This function controls the recursion, which only continues deeper if this callback returns true for a branch quadrant. It is allowed to set this to NULL.
• point_fn:[in] This function decides per-point whether it is followed down the recursion. Must be non-NULL if points are not NULL.
• points:[in] User-provided array of points that are passed to the callback point_fn. See p4estsearchlocal for details.

Prototype

void p4est_search_partition (p4est_t * p4est, int call_post, p4est_search_partition_t quadrant_fn, p4est_search_partition_t point_fn, sc_array_t * points);

p4est_source_ext(src, mpicomm, data_size, load_data, autopartition, broadcasthead, user_pointer, connectivity)

Prototype

p4est_t *p4est_source_ext (sc_io_source_t * src, sc_MPI_Comm mpicomm, size_t data_size, int load_data, int autopartition, int broadcasthead, void *user_pointer, p4est_connectivity_t ** connectivity);

p4est_split_array(array, level, indices)

Split an array of quadrants by the children of an ancestor.

Given a sorted array of quadrants that have a common ancestor at level level, compute the indices of the first quadrant in each of the common ancestor's children at level level + 1.

Parameters

• array:[in] The sorted array of quadrants of level > level.
• level:[in] The level at which there is a common ancestor.
• indices:[in,out] The indices of the first quadrant in each of the ancestors's children, plus an additional index on the end. The quadrants of array that are descendants of child i have indices between indices[i] and indices[i + 1] - 1. If indices[i] = indices[i+1], this indicates that no quadrant in the array is contained in child i.

Prototype

void p4est_split_array (sc_array_t * array, int level, size_t indices[]);

p4est_version()

Return the full version of p4est.

Returns

Return the version of p4est using the format VERSION\_MAJOR.VERSION\_MINOR.VERSION\_POINT, where VERSION_POINT can contain dots and characters, e.g. to indicate the additional number of commits and a git commit hash.

Prototype

const char *p4est_version (void);

p4est_version_major()

Return the major version of p4est.

Returns

Return the major version of p4est.

Prototype

int p4est_version_major (void);

p4est_version_minor()

Return the minor version of p4est.

Returns

Return the minor version of p4est.

Prototype

int p4est_version_minor (void);

p6est_balance(p6est_, btype, init_fn)

Balance a forest.

Parameters

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

Prototype

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

p6est_balance_ext(p6est_, btype, max_diff, min_diff, init_fn, replace_fn)

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

Parameters

• p6est:[in,out] The p6est to be worked on.
• btype:[in] Balance type (face or corner/full). Corner balance is almost never required when discretizing a PDE; just causes smoother mesh grading.
• max_diff:[in] The maximum difference between the horizontal refinement level and the vertical refinement level
• min_diff:[in] The minimum difference between the horizontal refinement level and the vertical refinement level
• init_fn:[in] Callback function to initialize the user_data which is already allocated automatically.
• replace_fn:[in] Callback function that allows the user to change incoming quadrants based on the quadrants they replace.

Prototype

void p6est_balance_ext (p6est_t * p6est, p8est_connect_type_t btype, int max_diff, int min_diff, p6est_init_t init_fn, p6est_replace_t replace_fn);

p6est_checksum(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.

Prototype

unsigned p6est_checksum (p6est_t * p6est);

p6est_coarsen_columns(p6est_, coarsen_recursive, coarsen_fn, init_fn)

Coarsen the columns of a sheet.

Parameters

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

Prototype

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

p6est_coarsen_columns_ext(p6est_, coarsen_recursive, callback_orphans, coarsen_fn, init_fn, replace_fn)

Horizontally coarsen a forest.

Parameters

• p6est:[in,out] The forest is changed in place.
• coarsen_recursive:[in] Boolean to decide on recursive coarsening.
• callback_orphans:[in] Boolean to enable calling coarsen_fn even on non-families. In this case, the second quadrant pointer in the argument list of the callback is NULL, subsequent pointers are undefined, and the return value is ignored. If coarsen_recursive is true, it is possible that a quadrant is called once or more as an orphan and eventually becomes part of a family.
• coarsen_fn:[in] Callback function that returns true if a family of quadrants shall be coarsened.
• init_fn:[in] Callback function to initialize the user_data which is already allocated automatically.
• replace_fn:[in] Callback function that allows the user to change incoming quadrants based on the quadrants they replace.

Prototype

void p6est_coarsen_columns_ext (p6est_t * p6est, int coarsen_recursive, int callback_orphans, p6est_coarsen_column_t coarsen_fn, p6est_init_t init_fn, p6est_replace_t replace_fn);

p6est_coarsen_layers(p6est_, coarsen_recursive, coarsen_fn, init_fn)

Coarsen the layers of a sheet.

Parameters

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

Prototype

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

p6est_coarsen_layers_ext(p6est_, coarsen_recursive, callback_orphans, coarsen_fn, init_fn, replace_fn)

Vertically coarsen a forest.

Parameters

• p6est:[in,out] The forest is changed in place.
• coarsen_recursive:[in] Boolean to decide on recursive coarsening.
• callback_orphans:[in] Boolean to enable calling coarsen_fn even on non-families. In this case, the second quadrant pointer in the argument list of the callback is NULL, subsequent pointers are undefined, and the return value is ignored. If coarsen_recursive is true, it is possible that a quadrant is called once or more as an orphan and eventually becomes part of a family.
• coarsen_fn:[in] Callback function that returns true if a family of quadrants shall be coarsened.
• init_fn:[in] Callback function to initialize the user_data which is already allocated automatically.
• replace_fn:[in] Callback function that allows the user to change incoming quadrants based on the quadrants they replace.

Prototype

void p6est_coarsen_layers_ext (p6est_t * p6est, int coarsen_recursive, int callback_orphans, p6est_coarsen_layer_t coarsen_fn, p6est_init_t init_fn, p6est_replace_t replace_fn);

p6est_compress_columns(p6est_)

Prototype

void p6est_compress_columns (p6est_t * p6est);

p6est_connectivity_destroy(conn)

Destroy a p6est_connectivity structure

Prototype

void p6est_connectivity_destroy (p6est_connectivity_t * conn);

p6est_connectivity_new(conn4, top_vertices, height)

Create a p6est_connectivity_t from a p4est_connectivity_t. All fields are copied, so all inputs can be safey destroyed.

Parameters

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

Returns

the 2D+1D connectivity information.

Prototype

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

p6est_copy(input, 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

• copy_data:[in] 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.

Prototype

p6est_t *p6est_copy (p6est_t * input, int copy_data);

p6est_copy_ext(input, copy_data, duplicate_mpicomm)

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. The inspect member of the copy is set to NULL.

Parameters

• copy_data:[in] If true, data are copied. If false, data_size is set to 0.
• duplicate_mpicomm:[in] If true, MPI communicator is copied.

Returns

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

Prototype

p6est_t *p6est_copy_ext (p6est_t * input, int copy_data, int duplicate_mpicomm);

p6est_destroy(p6est_)

Destroy a p6est.

Prototype

void p6est_destroy (p6est_t * p6est);

p6est_load(filename, mpicomm, data_size, load_data, user_pointer, connectivity)

Prototype

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);

p6est_load_ext(filename, mpicomm, data_size, load_data, autopartition, broadcasthead, user_pointer, connectivity)

Prototype

p6est_t *p6est_load_ext (const char *filename, sc_MPI_Comm mpicomm, size_t data_size, int load_data, int autopartition, int broadcasthead, void *user_pointer, p6est_connectivity_t ** connectivity);

p6est_new(mpicomm, connectivity, data_size, init_fn, user_pointer)

Prototype

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

p6est_new_ext(mpicomm, connectivity, min_quadrants, min_level, min_zlevel, num_zroot, fill_uniform, data_size, init_fn, user_pointer)

Prototype

p6est_t *p6est_new_ext (sc_MPI_Comm mpicomm, p6est_connectivity_t * connectivity, p4est_locidx_t min_quadrants, int min_level, int min_zlevel, int num_zroot, int fill_uniform, size_t data_size, p6est_init_t init_fn, void *user_pointer);

p6est_new_from_p4est(p4est_, top_vertices, height, min_zlevel, data_size, init_fn, user_pointer)

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

Parameters

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