/*
  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_simple2 Documentation for selected 2D example programs
 *
 * The p4est library comes with various example programs.
 * They are kept under the subdirectory
 * [example](https://github.com/cburstedde/p4est/tree/master/example).
 * Most have both a 2D and a 3D version.
 * When the library is configured `--enable-mpi`, they can all be run in
 * parallel on any number of MPI ranks, even on small computers.
 *
 * One first helpful program to try out is called `p4est_simple` (2D version)
 * and `p8est_simple` (3D version), both under
 * [simple](https://github.com/cburstedde/p4est/tree/master/example/simple).
 * We showcase some 2D results further below on this page, and we encourage
 * everyone to play with the command line arguments.
 *
 * ### The first step example
 *
 * Quite some time later, we created a range of step-by-step examples under
 * [steps](https://github.com/cburstedde/p4est/tree/master/example/steps).
 * Let us begin here with the first one that generates a mesh spelling
 * 'Hello, World!': \ref steps/p4est_step1.c.
 *
 *  This program performs refinement on a simple domain based on hardcoded
 * image data.
 * As a result, the output VTK file displays the phrase 'Hello World' by the
 * mesh refinement.
 *
 * Usage may be one of:
 *
 *  > `p4est_step1`
 *  or with MPI:
 *  > `mpirun -np 3 p4est_step1`
 *
 * * No. of trees: 1
 * * Maximum refinement level: 6
 *
 *  \image html HW.png
 *
 * ### The historic simple example
 *
 * Another illustrative example can be found in \ref simple/simple2.c.
 * The refinement pattern is generated by some hardcoded prescriptions based
 * on a quadrant's tree number, refinement level and coordinates.
 * Please see the documentation under that link for a full list of configurations.
 *
 * This program creates/refines & coarsens/balances/partitions one
 * of several available geometries specified on the command line.
 * As a result, the output VTK files document all
 * the steps of the mesh manipulation process.
 *
 *  * Example: periodic
 *
 *    Create a connectivity structure for a periodic unit square.
 * The left and right faces are identified, and bottom and top opposite.
 *
 *    Usage:
 *    > `p4est_simple periodic 5`
 *    or with MPI:
 *    > `mpirun -np 4 p4est_simple periodic 5`
 *
 *    * No. of trees: 1
 *    * Maximum refinement level: chosen on the command line as 5
 *
 *  \image html periodic_balanced_lv5.png
 *
 *  * Example: circle
 *
 *    Create a connectivity structure for an donut-like circle.
 * The circle consists of 6 trees connecting each other by their faces.
 * The trees are laid out as a hexagon between \f$[-2, 2]\f$ in the y direction
 * and \f$[-\sqrt{3}, \sqrt{3}]\f$ in the x direction.  The hexagon has flat
 * sides along the y direction and pointy ends in x.
 *
 *    Usage:
 *    > `p4est_simple circle 5`
 *    or with MPI:
 *    > `mpirun -np 4 p4est_simple circle 5`
 *
 *    * No. of trees: 6
 *    * Maximum refinement level: chosen on the command line as 5
 *
 *  \image html circle_balanced_lv5.png
 *
 *  * Example: drop
 *
 *    Create a connectivity structure for a five-trees geometry with a hole.
 * The geometry covers the square \f$[0, 3]^2\f$, where the hole is \f$[1, 2]^2\f$.
 *
 *    Usage:
 *    > `p4est_simple drop 5`
 *    or with MPI:
 *    > `mpirun -np 7 p4est_simple drop 5`
 *
 *    * No. of trees: 5
 *    * Maximum refinement level: chosen on the command line as 5
 *  \image html drop_balanced_lv5.png
 *
 *  * Example: moebius
 *
 *    Create a connectivity structure for a five-tree moebius band.
 *
 *    Usage:
 *    > `p4est_simple moebius 5`
 *    or with MPI:
 *    > `mpirun -np 4 p4est_simple moebius 5`
 *
 *    * No. of trees: 5
 *    * Maximum refinement level: chosen on the command line as 5
 *
 *  \image html moebius_balanced_lv5.png
 */

 /** \page example_simple3 Documentation for selected 3D example programs
 *
 * The p4est library comes with various example programs.
 * They are kept under the subdirectory
 * [example](https://github.com/cburstedde/p4est/tree/master/example).
 * Most have both a 2D and a 3D version.
 * When the library is configured `--enable-mpi`, they can all be run in
 * parallel on any number of MPI ranks, even on small computers.
 *
 * Before proceeding with the examples on this page, it is highly
 * recommended to get familiar with the programs, starting from 2D
 * examples in \ref example_simple2.
 *
 * One first helpful program to try out is called `p4est_simple` (2D version)
 * and `p8est_simple` (3D version), both under
 * [simple](https://github.com/cburstedde/p4est/tree/master/example/simple).
 * On this page, we showcase some results of 3D example programs further
 * below on this page, and we encourage everyone to play with the command
 * line arguments.
 *
 * ### The historic simple example
 *
 * The example can be found in \ref simple/simple3.c. It is a 3D version of
 * \ref simple/simple2.c
 * The refinement pattern is generated by some hardcoded prescriptions based
 * on a octants's tree number, refinement level and coordinates.
 * Please see the documentation under the link for a full list of configurations.
 *
 * This program creates/refines & coarsens/balances/partitions one
 * of several available geometries specified on the command line.
 * As a result, the output VTK files document all
 * the steps of the mesh manipulation process.
 *
 *  * Example: unit
 *
 *    Create a connectivity structure for a stand-alone unit cube.
 *
 *    Usage:
 *    > `p8est_simple unit 5`
 *    or with MPI:
 *    > `mpirun -np 4 p8est_simple unit 5`
 *
 *    * No. of trees: 1
 *    * Maximum refinement level: chosen on the command line as 5
 *
 *  \image html unit_balanced_lv5.png
 *
 *  * Example: periodic
 *
 *    Further enriching the upper example, this example program creates a
 * connectivity structure of a unit cube with all-periodic boundary conditions.
 *
 *    Usage:
 *    > `p8est_simple periodic 5`
 *    or with MPI:
 *    > `mpirun -np 4 p8est_simple periodic 5`
 *
 *    * No. of trees: 1
 *    * Maximum refinement level: chosen on the command line as 5
 *
 *  \image html periodic_3d_balanced_lv5.png
 *
 *  * Example: two wraps
 *
 *    Further developing the ideas above, this example program creates a
 * connectivity structure of two wrap-up cubes (each of which is a tree). The
 * visually not connected far ends of the two cubes are periodically identical.
 *
 *    Usage:
 *    > `p8est_simple twowraps 5`
 *    or with MPI:
 *    > `mpirun -np 7 p8est_simple twowraps 5`
 *
 *    * No. of trees: 2
 *    * Maximum refinement level: chosen on the command line as 5
 *  \image html twowraps_balanced_lv5.png
 *
 */

/** \example steps/p4est_step1.c
 *
 *  This software refines a basic domain using given image data.
 * As a result, the resulting VTK file showcases the message 'Hello
 * World' through the mesh.
 *
 * Usage:
 *    > `p4est_step1`
 */

/** \example simple/simple2.c
 *
 * This application (3D counterpart: \ref simple/simple3.c) generates, refines,
 * and adjusts a mesh set on the command line.
 * The resulting VTK files visually present each stage of the mesh modification
 * procedure.
 *
 * Usage:
 *    > `p4est_simple <configuration> <level>`
 *        possible configurations:
 *        * unit      Refinement on the unit square.
 *        * brick     Refinement on a regular forest of octrees.
 *        * three     Refinement on a forest with three trees.
 *        * evil      Check second round of refinement with np=5 level=7
 *        * evil3     Check second round of refinement on three trees
 *        * pillow    Refinement on a 2-tree pillow-shaped domain.
 *        * moebius   Refinement on a 5-tree Moebius band.
 *        * star      Refinement on a 6-tree star shaped domain.
 *        * cubed     Refinement on a 6-tree cubed sphere surface.
 *        * disk      Refinement on a 5-tree spherical standard disk.
 *        * xdisk     Refinement on a 5-tree spherical disk periodic in x.
 *        * ydisk     Refinement on a 5-tree spherical disk periodic in y.
 *        * pdisk     Refinement on a 5-tree spherical disk, periodic b.c.
 *        * periodic  Refinement on the unit square with all-periodic b.c.
 *        * rotwrap   Refinement on the unit square with weird periodic b.c.
 *        * circle    Refinement on a 6-tree donut-like circle.
 *        * drop      Refinement on a 5-trees geometry with an inner hole.
 *        * icosahedron   Refinement on the sphere
 *        * shell2d       Refinement on a 2d shell with geometry.
 *        * disk2d        Refinement on a 2d disk with geometry.
 *        * bowtie    Refinement on a 2-tree bowtie domain.
 */

/** \example simple/simple3.c
 *
 * This 3D application generates, refines, and adjusts a mesh set on the
 * command line.
 * The resulting VTK files visually present each stage of the mesh
 * modification procedure.
 *
 * Usage:
 *    > `p8est_simple <configuration> <level>`
 *        possible configurations:
 *        * unit      The unit cube.
 *        * brick     The brick connectivity.
 *        * periodic  The unit cube with all-periodic boundary conditions.
 *        * rotwrap   The unit cube with various self-periodic b.c.
 *        * twocubes  Two connected cubes.
 *        * twowrap   Two cubes with periodically identified far ends.
 *        * rotcubes  A collection of six connected rotated cubes.
 *        * shell     A 24-tree discretization of a hollow sphere.
 *        * sphere    A 13-tree discretization of a solid sphere.
 */
