Example: simple

doc/Doxyfile.in

@@ -856,7 +856,8 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = @top_srcdir@/src \
-                         @top_srcdir@/doc/mainpage.dox
+                         @top_srcdir@/doc/mainpage.dox \
+                         @top_srcdir@/doc/examples.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -934,7 +935,7 @@ EXCLUDE_SYMBOLS        = SC_EXTERN_C_BEGIN \
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = @top_srcdir@/example/steps
+EXAMPLE_PATH           = @top_srcdir@/example/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -955,7 +956,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = @top_srcdir@/doc/images
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -2167,15 +2168,15 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
 # EXPAND_AS_DEFINED tags.
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2207,7 +2208,8 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = @PACKAGE_PREFIX@_DOXYGEN
+PREDEFINED             = @PACKAGE_PREFIX@_DOXYGEN __attribute__(x)= \
+                         P4EST_WITH_METIS
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

doc/author_hongli.txt

@@ -0,0 +1 @@
+I place my contributions to p4est under the FreeBSD license. Hongli Lin (lin@ins.uni-bonn.de)

doc/examples.dox

@@ -0,0 +1,174 @@
+/*
+  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 Examples 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
+ */
+
+/** \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/simple2.c

@@ -40,9 +40,12 @@
  *        o pdisk     Refinement on a 5-tree spherical disk, periodic b.c.
  *        o periodic  Refinement on the unit square with all-periodic b.c.
  *        o rotwrap   Refinement on the unit square with weird periodic b.c.
+ *        o circle    Refinement on a 6-tree donut-like circle.
+ *        o drop      Refinement on a 5-trees geometry with an inner hole.
  *        o icosahedron   Refinement on the sphere
  *        o shell2d       Refinement on a 2d shell with geometry.
  *        o disk2d        Refinement on a 2d disk with geometry.
+ *        o bowtie    Refinement on a 2-tree bowtie domain.
  */
 
 #include <p4est_bits.h>
@@ -67,9 +70,12 @@ typedef enum
   P4EST_CONFIG_PDISK,
   P4EST_CONFIG_PERIODIC,
   P4EST_CONFIG_ROTWRAP,
+  P4EST_CONFIG_CIRCLE,
+  P4EST_CONFIG_DROP,
   P4EST_CONFIG_ICOSAHEDRON,
   P4EST_CONFIG_SHELL2D,
   P4EST_CONFIG_DISK2D,
+  P4EST_CONFIG_BOWTIE,
   P4EST_CONFIG_LAST
 }
 simple_config_t;
@@ -121,6 +127,9 @@ static const simple_regression_t regression[] =
  { P4EST_CONFIG_PDISK, 5, 5, 0x507fd0c9 },
  { P4EST_CONFIG_ROTWRAP, 1, 6, 0x9dd600c5U },
  { P4EST_CONFIG_ROTWRAP, 3, 6, 0x9dd600c5U },
+ { P4EST_CONFIG_CIRCLE, 3, 6, 0xd6e4931b },
+ { P4EST_CONFIG_DROP, 3, 6, 0xea6a6726 },
+ { P4EST_CONFIG_BOWTIE, 1, 3, 0x63ba0805 },
  { P4EST_CONFIG_NULL, 0, 0, 0 }};
 /* *INDENT-ON* */
 
@@ -264,7 +273,7 @@ main (int argc, char **argv)
   p4est_coarsen_t     coarsen_fn;
   simple_config_t     config;
   const simple_regression_t *r;
-  int                 nbrick_x=1, nbrick_y=1;
+  int                 nbrick_x = 1, nbrick_y = 1;
 
   /* initialize MPI and p4est internals */
   mpiret = sc_MPI_Init (&argc, &argv);
@@ -284,7 +293,7 @@ main (int argc, char **argv)
     "   Configuration can be any of\n"
     "      unit|brick|three|evil|evil3|pillow|moebius|\n"
     "         star|cubed|disk|xdisk|ydisk|pdisk|periodic|\n"
-    "         rotwrap|icosahedron|shell2d|disk2d\n"
+    "         rotwrap|circle|drop|icosahedron|shell2d|disk2d|bowtie\n"
     "   Level controls the maximum depth of refinement\n";
   wrongusage = 0;
   config = P4EST_CONFIG_NULL;
@@ -337,6 +346,12 @@ main (int argc, char **argv)
     else if (!strcmp (argv[1], "rotwrap")) {
       config = P4EST_CONFIG_ROTWRAP;
     }
+    else if (!strcmp (argv[1], "circle")) {
+      config = P4EST_CONFIG_CIRCLE;
+    }
+    else if (!strcmp (argv[1], "drop")) {
+      config = P4EST_CONFIG_DROP;
+    }
     else if (!strcmp (argv[1], "icosahedron")) {
       config = P4EST_CONFIG_ICOSAHEDRON;
     }
@@ -346,6 +361,9 @@ main (int argc, char **argv)
     else if (!strcmp (argv[1], "disk2d")) {
       config = P4EST_CONFIG_DISK2D;
     }
+    else if (!strcmp (argv[1], "bowtie")) {
+      config = P4EST_CONFIG_BOWTIE;
+    }
     else {
       wrongusage = 1;
     }
@@ -377,8 +395,8 @@ main (int argc, char **argv)
   /* create connectivity and forest structures */
   geom = NULL;
   if (config == P4EST_CONFIG_BRICK) {
-    nbrick_x = argc > 3 ? atoi(argv[3]) : 3;
-    nbrick_y = argc > 4 ? atoi(argv[4]) : 2;
+    nbrick_x = argc > 3 ? atoi (argv[3]) : 3;
+    nbrick_y = argc > 4 ? atoi (argv[4]) : 2;
     connectivity = p4est_connectivity_new_brick (nbrick_x, nbrick_y, 0, 0);
   }
   else if (config == P4EST_CONFIG_THREE || config == P4EST_CONFIG_EVIL3) {
@@ -414,6 +432,12 @@ main (int argc, char **argv)
   else if (config == P4EST_CONFIG_ROTWRAP) {
     connectivity = p4est_connectivity_new_rotwrap ();
   }
+  else if (config == P4EST_CONFIG_CIRCLE) {
+    connectivity = p4est_connectivity_new_circle ();
+  }
+  else if (config == P4EST_CONFIG_DROP) {
+    connectivity = p4est_connectivity_new_drop ();
+  }
   else if (config == P4EST_CONFIG_ICOSAHEDRON) {
     double              R = 1.0;        /* sphere radius default value */
 
@@ -431,6 +455,9 @@ main (int argc, char **argv)
     connectivity = p4est_connectivity_new_disk2d ();
     geom = p4est_geometry_new_disk2d (connectivity, 0.44, 1.0);
   }
+  else if (config == P4EST_CONFIG_BOWTIE) {
+    connectivity = p4est_connectivity_new_bowtie ();
+  }
   else {
     connectivity = p4est_connectivity_new_unitsquare ();
   }