diff --git a/doc/doxygen/forest.dox b/doc/doxygen/forest.dox new file mode 100644 index 000000000..5accc4baf --- /dev/null +++ b/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. + */ diff --git a/doc/release_notes.txt b/doc/release_notes.txt index ed4564c12..16381a178 100644 --- a/doc/release_notes.txt +++ b/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