Merge pull request #260 from SAutum/p8est_doc

Example 3d: documentation

doc/doxygen/example_simple.dox

@@ -21,7 +21,7 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** \page example_simple Documentation for selected example programs
+/** \page example_simple2 Documentation for selected 2D example programs
  *
  * The p4est library comes with various example programs.
  * They are kept under the subdirectory
@@ -33,7 +33,7 @@
  * 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
+ * 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
@@ -133,6 +133,85 @@
  *  \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
@@ -172,3 +251,22 @@
  *        * 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.
+ */