p8est_doc: recover the documentation of example 3d

doc/doxygen/example_simple.dox

@@ -0,0 +1,272 @@
+/*
+  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_simple Documentation for selected 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 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 Examples2 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 Examples.
+ *
+ * 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 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 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.
+ */