This is the README file for p4est.

p4est is a C library to manage a collection (a forest) of multiple
connected adaptive quadtrees or octrees in parallel.

p4est is written by Carsten Burstedde, Lucas C. Wilcox, and Tobin Isaac
and released under the GNU General Public Licence version 2 (or later),
Copyright (C) 2010 The University of Texas System.

The official web page for source code and documentation is www.p4est.org.
Please send bug reports and ideas for contribution to info@p4est.org.


 0. Acknowledgement and Disclaimer

The development of p4est was partially supported by the US National Science
Foundation (NSF Grants No. OCI-0749334, CCF-0427985, CNS-0540372, CNS-0619838,
DMS-0724746, OPP-0941678) and the US Department of Energy (DOE Grants No.
06ER25782, 08ER25860, SC0002710).  The authors thank the Texas Advanced
Computing Center (TACC) for providing them with access to the Ranger
supercomputer under NSF TeraGrid award MCA04N026, and the National Center for
Computational Science (NCCS) for early-user access to the Jaguar Cray XT5
supercomputer.  Any opinions, findings and conclusions or recomendations
expressed in the source code and documentation are those of the authors and do
not necessarily reflect the views of the National Science Foundation (NSF).


 1. Purpose

Many applications in applied mathematics and numerical simulation use a mesh of
computation cells that covers the domain of interest.  The numerical solution
is then approximated by functions, each of which is associated with a small set
of cells (or even one).  Dynamic ``adaptive'' methods change the mesh during
the simulation by local refinement or coarsening, and ``parallel'' methods
distribute (``partition'') the mesh between multiple processors, where each
processor ideally receives an equal share of the computational load.  p4est
isolates the task of parallel dynamic adaptive mesh refinement (AMR),
coarsening, and load balancing, and encapsulates algorithms that scale well to
large numbers (10^5) of processors.


 2. Geometric structure

The basic structure used in p4est is a ``connectivity'' of quadtrees (2D) or
octrees (3D) which covers the domain of interest in a conforming macro-mesh.
These trees can then be arbitrarily refined and coarsened, where the storage of
quadrants/octants is distributed in parallel.  Thus, the mesh primitives used
in p4est are quadrilaterals in 2D and hexahedra in 3D.  The adaptive structure
allows for quadrants/octants of different sizes to neighbor each other, which
is commonly called ``non-conforming''.  This concept leads to ``hanging'' faces
and edges.


 3. Core p4est (2D) and p8est (3D) routines

p?est_new: Create an equi-partitioned, uniformly refined forest.

p?est_refine: Adaptively subdivide octants based on a callback function, once
for each octant or recursively.

p?est_coarsen: Replace families of eight child octants by their common parent
octant, once or recursively.

p?est_partition: Redistribute the octants in parallel, according to a given
target number of octants for each process, or weights prescribed for all
octants.

p?est_balance: Ensure at most 2:1 size relations between neighboring octants by
local refinement where necessary.

p?est_checksum: Compute a partition-independent integer ``fingerprint'' of a
forest.  This is useful for debugging and regression testing.


 4. Interfacing to p4est from applications

p?est_ghost: Collect one layer of off-process octants touching the process
boundaries from the outside.  This function requires a previous call to
p?est_balance.  This is the most generally useful function for external
applications.  By querying the ghost layer, the application can associate
degrees of freedom with the mesh which are the basis for all numerical
computation.

p?est_nodes: Create a globally unique numbering of the mesh nodes (i.e., the
vertices at the corners of octants, not to be confused with octree nodes),
taking into account the classification into ``independent'' and ``hanging''
nodes.  This function requires previous calls to p?est_balance and p?est_ghost.
It provides a global numbering for degrees of freedom that can be associated
with piecewise linear finite elements.


 5. Installation

p4est uses the GNU autoconf/automake/libtool build system.  See the INSTALL
file for details.  The following configure options are important.

--enable-mpi: Necessary for parallel functionality.  Without this option, p4est
does not require MPI, which is replaced by a dummy implementation that always
assumes an MPI_Comm_size of 1 and an MPI_Comm_rank of 0.

--enable-debug: Enable assertions and additional code for verification.  This
is generally helpful for development, even if it is somewhat slower and
produces a lot of diagnostic log messages.


 6. Using p4est through the deal.II interface

The recent development version of the generic adaptive finite element software
library deal.II interfaces to p4est to parallelize its mesh handling.  The most
convenient way to compile and install p4est to be accessible for deal.II is to
use the doc/p4est-setup.sh script.  This creates both a debug and production
version compiled with minimal logging output.  To know what is going on within
p4est, the log level needs to be relaxed in the script.