The forest-of-octrees coordinate system.

A p4est mesh is constructed by first defining one or more trees, each of which is logically a square (2D) or cube (3D), and linking them where they touch topologically. This creates an unstructured conforming hexahedral mesh. The trees may be arbitrarily rotated and folded back onto each other. Thus, the all-periodic unit cube is a possibility as well as a Moebius strip or other self-connecting connectivities. Of course, a simple unit cube or a rectangular brick pattern works fine. It is also possible to convert the output of a hex mesh generator to a p4est connectivity programmatically. For details, please see the page on The connectivity structure.

Each tree can be filled by a single root quadrant, for example by calling p4est_quadrant_root, or a set of descendants as long as there are no gaps or overlaps between the quadrants. Quadrants may be refined calling p4est_quadrant_children, and aggregated back to their common parent by p4est_quadrant_parent. These quadrants are positioned within the unit tree by the coordinate tuple of their lower left corner. We use an integer coordinate system for the quadrant coordinates. The lower left corner of the tree is at the origin, and the length of the unit tree is P4EST_ROOT_LEN. The latter variable is equal to the number of quadrants in one direction at the deepest possible refinement level P4EST_MAXLEVEL with one caveat discussed as follows.

Sometimes it is useful to distinguish the coordinates of all quadrant boundary points: its corners, face midpoints, edge midpoints in 3D, and the volume midpoint. There are 3** P4EST_DIM, or P4EST_INSUL, of these points total. Since they sit at the half-length of the quadrant, we allow quadrants only as deep (fine) as they still separate all midpoints by at least one. This is the reason that quadrants may only be refined one level less than coordinates, namely to P4EST_QMAXLEVEL.

Quadrants have finite length, so their lower left coordinates are always strictly less than P4EST_ROOT_LEN. The quadrant boundary coordinates on the upper right may however reach to this value inclusively. This means coordinates are still considered inside the unit tree, p4est_coordinates_is_inside_root, when they are on any tree boundary. For quadrants, this is only true for its origin point, verified by p4est_quadrant_is_inside_root.

The discussion so far applies regardless to which tree a quadrant is considered to be in. We never store the tree number directly inside a mesh quadrant (we only do this for interface/meta structures like the p4est_ghost_t layer). The tree is usually apparent by context, since each tree stores its local quadrants in a separate array. Still, when trees touch at some (tree corner, edge, or face) point, that coordinate may have different values seen from any of the touching trees.

If the need arises to determine a unique coordinate representation of an inter-tree boundary point, for example for hashing, see p4est_connectivity_coordinates_canonicalize. This function uses the tree neighbor information in the p4est_connectivity_t to calculate the lowest tree number this coordinate point touches, and the coordinate values transformed into that tree's system. If a coordinate touches the same tree in different places (like for a periodic mesh), it calculates the lowest coordinate among those touching the lowest numbered tree.

In practice, coordinates are rarely used. However, they provide a convenient route to identify quadrant neighbors, since for example a mesh corner at the cross of four (2D) or eight (3D) quadrants leads to the same coordinate tuple and derived hash from all of these perspectives. For an example of using this mechanism, and as a guide to use the hash functionality available, see test_coordinates2.c (containing code for both the 2D and the 3D program).