/*
  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 example_userdata A demonstration of how to manage application data
 *
 * This is an example of a typical application workflow with associated data.
 *
 * By design \ref p4est is agnostic of any application data.  It supports
 * two major ways of the application developer managing their simulation
 * data:
 * Stashing it into \ref p4est's quadrant data storage or leaving it
 * external to \ref p4est, allocated and maintained by the application
 * developer.
 * Both approaches may be combined, for example to store refinement flags
 * in the quadrant data and numerical fields outside of p4est.
 *
 * We review both ways below and close with general recommendations.
 * For simplicity, we reference 2D function calls in this document, all of
 * which have analogous versions in 3D.
 *
 * ## p4est-internal element data
 *
 * In \ref p4est, an element is the leaf node of a quadtree (2D) or octree
 * (3D).
 * In the code, we call all nodes of a tree a quadrant, including leaves.
 * The library maintains internal data for each element, to which a fixed
 * amount of user data may be added.
 * If \ref p4est_new_ext or \ref p4est_reset_data is called with a nonzero
 * data size, \ref p4est allocates and maintains this amount of storage in
 * each quadrant.
 * It is accessible to the application developer by the \c p.user_data
 * pointer in each \ref p4est_quadrant.
 *
 * The user data may be initialized by the \ref p4est_init_t callback to the
 * forest \b new, \b refine, \b coarsen, and \b balance functions, for
 * example \ref p4est_refine_ext (see \ref p4est.h and \ref
 * p4est_extended.h).
 *
 * The data may be updated by any other callback to these functions, for
 * example \ref p4est_refine_t or \ref p4est_replace_t.
 * Likewise, the data is accessible from the \ref p4est_iter_volume_t
 * callback as the \c quad member of the \ref p4est_iter_volume_info
 * argument.
 * The volume iterator may be called on a valid forest any time, even
 * without a \ref p4est_ghost layer being present.
 *
 * And finally, the user is very welcome to loop manually over all local
 * trees and their quadrants to access their data.
 *
 * On \b repartitioning the mesh for load balancing, the quadrant user data
 * is transferred transparently inside \ref p4est_partition.
 *
 * We also provide the \ref p4est_ghost_exchange_data function to gather the
 * user data of all remote quadrants neighboring to a process.
 *
 * This approach is well suited for typical amounts of refinement metadata
 * (such as indicators and flags) and lightweight numerical data.
 * It is fixed-size: each quadrant has the exact same amount of user data.
 *
 * ## User-allocated element data
 *
 * The second part of the example keeps the simulation data in a flat array
 * of values outside of p4est.
 * We still use internal quadrant data but only for refinement and
 * coarsening flags, which are computed by iterating simultaneously over the
 * quadrants and the array of application data using \ref p4est_iterate.
 *
 * Here, we make a new copy of the current mesh and then modify it as in the
 * previous example, but without touching the data while it is in progress.
 * Then we invoke a piece of custom code to traverse both the current and
 * new mesh and their data arrays to transfer the values to the new
 * resolution.
 * Afterwards, we delete the current mesh and data array and make the new
 * ones current.
 * This idea can be copied as needed by anyone to interpolate their own
 * data.
 * It is a powerful approach.
 *
 * To load-balance after adaptation (or for any other reason), we again make
 * a copy of the current mesh and partition that.
 * This transfers internal quadrant data but not yet the simulation data.
 * To effect this, we call \ref p4est_transfer_fixed on the old data array
 * and a newly allocated one for the results.
 * Afterwards, we delete the current mesh and data and make the new ones
 * current.
 *
 * This approach can be extended to data that is of variable size between
 * the mesh elements.
 * On the application developer side, this requires just some more
 * bookkeeping of memory offsets.
 * In this case, the transfer on repartition can be accomplished using \ref
 * p4est_transfer_custom.
 * We currently do not have a variable-size variant of \ref
 * p4est_ghost_exchange, but the interested user is welcome to write it and
 * propose a pull request.
 *
 * All transfer functions have a version that is split between begin and end
 * to overlap communication with computation.
 *
 * ## Which way should I choose?
 *
 * The source code for this demonstration resides in \ref
 * userdata/userdata_run2.c (2D) and \ref userdata/userdata_run3.c (3D).
 * You may run any of these examples and examine the difference in the VTK
 * outputs of the two methods (easiest when configured
 * `--disable-vtk-binary`).
 * There will be some (too small to affect the rate of convergence) in line
 * with the following analysis.
 *
 * The demo with internal data interpolates and projects data on the fly In
 * the same round of adaptation.  It may happen that a quadrant is refined
 * and immediately coarsened, or coarsened and immediately refined again.
 * Both cases waste some amount of computation, and in the latter case, we
 * slightly decrease accuracy.
 * While such is usually harmless, it can be avoided altogether by extending
 * the quadrant data with refinement metadata.
 * This is left as an exercise to the reader.
 *
 * We have specifically written the demo with external data such that it
 * avoids the above issue by design.
 * Since quadrant data and application data are independent, we can execute
 * a full round of refinement, coarsening and 2:1 balance on the mesh and
 * only update the application data once after that is done.
 *
 * We lean towards keeping flags and other small context data in the
 * quadrant storage internal to p4est, and possibly the simulation data when
 * writing examples quickly.
 * For more serious applications and memory demands, the data may be kept
 * explicitly in user-allocated arrays as demonstrated here.
 */

/** \example userdata/userdata2.c
 *
 * A 2D example of managing application data: **main program**.
 *
 * The detailed code for the demonstration resides in \ref
 * userdata/userdata_run2.c.
 *
 * The workflow is documented more extensively in \ref example_userdata.
 */

/** \example userdata/userdata_run2.c
 *
 * A 2D example of managing application data: **core code**.
 *
 * The workflow is documented more extensively in \ref example_userdata.
 *
 * This file contains the code compiled for both the 2D and 3D demo.  This
 * is accomplished with only minimal redefinitions.  We write the code only
 * once and use it twice.  The 3D source \ref userdata/userdata_run3.c is a
 * formal wrapper.  In this sense, the code is mostly dimension independent.
 *
 * This file contains the detailed code of the demo.  Its entry point is
 * called from \ref userdata/userdata2.c, which is a good example of setting
 * up a **main program** and defining and parsing command line options.
 */

/** \example userdata/userdata_run3.c
 *
 * A 3D example of managing application data.
 *
 * The workflow is documented more extensively in \ref example_userdata.
 * The image below is generated from the command
 *
 *     mpirun -np 7 example/userdata/p8est_userdata rotcubes 5 -I
 *
 * and visualized with Paraview, combining a value threshold of 0.1 and up
 * with an output of level 3 cells colored by MPI rank.
 * \image html userdata_rotcubes_lv5.png
 *
 * The 3D version of th this demo compiles from the same code as the 2D
 * example \ref userdata/userdata_run2.c with minimal redefinitions.  In
 * this sense, the code is mostly dimension independent.
 */
