Add a doxygen page on the forest workflow

doc/doxygen/forest.dox

@@ -0,0 +1,166 @@
+/*
+  This file is part of p4est.
+  p4est is a C library to manage a collection (a forest) of multiple
+  connected adaptive quadtrees or octrees in parallel.
+
+  Copyright (C) 2010 The University of Texas System
+  Written by Carsten Burstedde, Lucas C. Wilcox, and Tobin Isaac
+
+  p4est is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  p4est is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with p4est; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/** \page forest The forest workflow
+ *
+ * An overview of the forest of octrees creation and manipulation.
+ *
+ * ## Introduction
+ * The forest data structure (cf. \ref p4est_t (2D), \ref p8est_t (3D)) encodes
+ * the mesh topology as a forest of quadtrees (2D) or octrees (3D).
+ * The forest can be created given a connectivity (cf. the
+ * [connectivity page](\ref connectivity)).
+ * In contrast to the connectivity data structure, the forest data structure is
+ * distributed in memory when MPI is activated, i.e. the forest data structure
+ * only stores leaves that are processor-local according to the parallel mesh
+ * partition.
+ * This page provides an overview of the typical workflow in p4est to create and
+ * manipulate such a forest to represent the desired mesh topology.
+ *
+ * ## Forest creation
+ * A fundamental step in a typical workflow with p4est is to create a forest of
+ * quadtrees or octrees. The p4est library offers the functions \ref p4est_new
+ * (2D), \ref p8est_new (3D) and \ref p4est_new_ext (2D), \ref p8est_new_ext
+ * (3D) (versions with additional parameters) to create such a forest.
+ *
+ * Creating a forest that encodes a partition-independent 2D mesh:
+ * \code{.c}
+ * /* user data structure for the data inside each forest leaf */
+ * typedef struct my_user_data {
+ *  int foo;
+ * }
+ * my_user_data_t;
+ *
+ * /* callback function to initialize the data in each forest leaf */
+ * static void
+ * my_quadrant_init (p4est, which_tree, quadrant) {
+ *  ((my_user_data_t *) quadrant->p.user_data)->foo = *(int *) p4est->user_pointer;
+ * }
+ *
+ * static int foo = 17489;
+ * void *user_pointer = &foo;
+ *
+ * forest = p4est_new_ext (mpicomm, connectivity, 0, level, 1,
+ *                         sizeof (my_user_data_t), my_quadrant_init, user_pointer);
+ * \endcode
+ *
+ * \b mpicomm is an MPI communicator (cf. \ref simple/simple2.c for a usage
+ * example).
+ *
+ * The highest occurring level of refinement is specified by the \b level
+ * parameter.
+ * If it is zero or negative, there will be no refinement beyond the coarse mesh
+ * connectivity at this point.
+ *
+ * We provide an optional callback mechanism (cf. \b my_quadrant_init above) to
+ * initialize the user data that we allocate inside each forest leaf.
+ *
+ * The \b user_pointer is assigned to the member of the same name in the
+ * created \b forest (before the init callback function is called the first
+ * time).
+ * This is a way to keep the application state referenced in a forest object.
+ *
+ * The resulting \b forest object in the above example represents a uniform mesh
+ * (with the coarse mesh topolgy as encoded in the passed \b connectivity)
+ * refined to the specified level.
+ * It is also possible to create a partition-dependent mesh by changing the two
+ * parameters set to 0 and 1 in the example above.
+ * However, for maximal reproducibility, we recommend to create a
+ * partition-independent mesh.
+ *
+ * For more details on the function parameters see \ref p4est.h and \ref
+ * p4est_extended.h -- as always, the 3D equivalents are prefixed with p8est.
+ *
+ * ## Manipulate the forest's refinement structure and partition
+ * There are two types of forest manipulation.
+ * The first is to manipulate the mesh that the forest represents and the
+ * second is to the manipulate the parallel partition of the forest, i.e.
+ * the parallel distribution of the leaves.
+ * All forest manipulation functions in p4est manipulate either the mesh or the
+ * partition but not both.
+ * This means that the functions for changing the refinement
+ * structure do not involve MPI communication.
+ *
+ * All forest manipulation functions are collective over the MPI communicator
+ * passed during the forest creation.
+ *
+ * ### Functions to manipulate forest's refinement structure
+ * - \ref p4est_refine Refinement of specific hypercubes given a refinement
+ * criterion, i.e. a user-defined callback function. While it is possible to
+ * enable recursive refinement, in practice we set it to non-recursive
+ * and loop around the function. This has the advantage that we can repartition
+ * in parallel after every iteration.
+ *
+ * - \ref p4est_coarsen Coarsen a family of hypercubes given a coarsening
+ * criterion, i.e. a user-defined callback function. This function is
+ * partition-dependent if families of leaves are split across processes.
+ * Partition-independent forests created using \ref p4est_new or \ref
+ * p4est_new_ext as described above do not split families among proccesses.
+ * In the case that the forest's partition is adjusted, the last call of \ref
+ * p4est_partition or \ref p4est_partition_ext must be with
+ * allow_for_coarsening activated (cf. the next section) to ensure
+ * partition-independent coarsening results.
+ *
+ * - \ref p4est_balance Ensure a 2:1 balance of the size differences of
+ * neighboring elements in a forest by refining mesh elements.
+ * This is accomplished by adding some more refinement where needed.
+ *
+ * For all three ways of manipulating the forest's refinement structure the user
+ * may pass a [callback](\ref p4est_init_t) to initialize the user data of the
+ * newly created leaves.
+ *
+ * Except of the mentioned special requirements for \ref p4est_coarsen all
+ * refinement structure manipulating functions are independent of the forest's
+ * partition.
+ *
+ * All of the listed functions have a version with extended options declared
+ * in \ref p4est_extended.h (2D) and \ref p8est_extended.h (3D).
+ *
+ * ### Function to manipulate the forest's partition
+ * The forest's partition is a parallel, disjoint and linear subdivision of
+ * the forest's leaves among the MPI processes.
+ * The partition is computed using the Morton curve as space-filling curve.
+ *
+ * The functions \ref p4est_new and \ref p4est_new_ext create a uniformly
+ * partitioned forest with respect to the leaf count.
+ * However, after manipulating the forest's refinement structure, the partition
+ * may no longer be uniform.
+ * Another reason for manipulating the partition is that the application
+ * may desire to partition the leaves according to the work associated with them
+ * instead of the leaf count.
+ * Manipulating the partition incurs MPI communication since the leaves and
+ * their data are shipped.
+ *
+ * - \ref p4est_partition Partition the forest in parallel, equally with respect
+ * to the leaf count or according to a given user-defined weight per leaf.
+ * The parameter \b allow_for_coarsening can be used to ensure that families of
+ * leaves are assigned to the same process -- cf. \ref p4est_coarsen.
+ *
+ * ## Examples of forest workflows
+ * Simple examples of typical forest workflows can be found in \ref
+ * simple/simple2.c (2D) and \ref simple/simple3.c (3D).
+ * A more application-oriented example can be found in \ref steps/p4est_step3.c
+ * (2D) and \ref steps/p8est_step3.c (3D).
+ * This example shows in particular the handling of leaf data for a simple
+ * advection solver.
+ */

doc/release_notes.txt

@@ -21,6 +21,7 @@
 
  - CMake system updates analogous to those in libsc.
  - Make the CI configuration more long-term stable.
+ - Add creation of the file .tarball-version in CMake.
 
 ### Documentation
 
@@ -30,6 +31,7 @@
  - Extend the documentation of the piggies in the quadrant data.
  - Add the p{4,8}est_step3 and timings as examples in doxygen.
  - Add a doxygen page on the connectivity structure.
+ - Add a doxygen page on the forest workflow.
 
 ### Functionality