example: two crashed examples

doc/release_notes.txt

@@ -21,8 +21,18 @@ This is the upcoming release with lots of small additions throughout.
 
 ### Documentation
 
+ - Create a navigation page of examples for users to get familiar with the
+   software.
+ - Fix the warnings while generating documentation for p4est_connectivity.h.
+ - Fix the warnings while generating documentation for p8est_connectivity.h.
+ - Add more explicit documentation to the p?est_connectivity.h files.
+
 ### Functionality
 
+ - Add two connectivities (2d bowtie and 3d drop) to stress the balance demo.
+ - Add a new 3d connectivity (drop) into the simple example.
+ - Add three 2d connectivities (circle, drop and bowtie) into simple.
+
 ## 2.8.5
 
 This was the last version without a release notes file.

example/balance/Makefile.am

@@ -5,19 +5,25 @@
 
 if P4EST_ENABLE_BUILD_2D
 bin_PROGRAMS += example/balance/p4est_balance_seeds
+bin_PROGRAMS += example/balance/p4est_balance_corner
 
 example_balance_p4est_balance_seeds_SOURCES = \
         example/balance/balance_seeds2.c
+example_balance_p4est_balance_corner_SOURCES = \
+        example/balance/balance_corner2.c
 
 LINT_CSOURCES += \
         $(example_balance_p4est_balance_seeds_SOURCES)
 endif
 
 if P4EST_ENABLE_BUILD_3D
 bin_PROGRAMS += example/balance/p8est_balance_seeds
+bin_PROGRAMS += example/balance/p8est_balance_corner
 
 example_balance_p8est_balance_seeds_SOURCES = \
         example/balance/balance_seeds3.c
+example_balance_p8est_balance_corner_SOURCES = \
+        example/balance/balance_corner3.c
 
 LINT_CSOURCES += \
         $(example_balance_p8est_balance_seeds_SOURCES)

example/balance/balance_corner2.c

@@ -0,0 +1,160 @@
+/*
+  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
+  Additional copyright (C) 2011 individual authors
+  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.
+*/
+
+#ifndef P4_TO_P8
+#include <p4est_bits.h>
+#include <p4est_extended.h>
+#include <p4est_vtk.h>
+#else
+#include <p8est_bits.h>
+#include <p8est_extended.h>
+#include <p8est_vtk.h>
+#endif
+
+typedef struct
+{
+  p4est_topidx_t      a;
+}
+user_data_t;
+
+typedef struct
+{
+  sc_MPI_Comm         mpicomm;
+  int                 mpisize;
+  int                 mpirank;
+}
+mpi_context_t;
+
+/* refinement level initialization */
+static int          refine_level = 0;
+
+/* connectivity initialization function */
+static void
+init_fn (p4est_t * p4est, p4est_topidx_t which_tree,
+         p4est_quadrant_t * quadrant)
+{
+  user_data_t        *data = (user_data_t *) quadrant->p.user_data;
+
+  data->a = which_tree;
+}
+
+/* refinement function */
+static int
+refine_fn (p4est_t * p4est, p4est_topidx_t which_tree,
+           p4est_quadrant_t * quadrant)
+{
+  if ((int) quadrant->level >= (refine_level - (int) (which_tree % 3))) {
+    return 0;
+  }
+  if (quadrant->level == 1 && p4est_quadrant_child_id (quadrant) == 3) {
+    return 1;
+  }
+  if (quadrant->x == P4EST_LAST_OFFSET (2) &&
+      quadrant->y == P4EST_LAST_OFFSET (2)) {
+    return 1;
+  }
+  if (quadrant->x >= P4EST_QUADRANT_LEN (2)) {
+    return 0;
+  }
+
+  return 1;
+}
+
+int
+main (int argc, char **argv)
+{
+  int                 mpiret;
+  int                 wrongusage;
+  const char         *usage;
+  p4est_connectivity_t *connectivity;
+  mpi_context_t       mpi_context, *mpi = &mpi_context;
+  p4est_geometry_t   *geom;
+  p4est_t            *p4est;
+
+  /* initialize MPI and p4est internals */
+  mpiret = sc_MPI_Init (&argc, &argv);
+  SC_CHECK_MPI (mpiret);
+  mpi->mpicomm = sc_MPI_COMM_WORLD;
+  mpiret = sc_MPI_Comm_size (mpi->mpicomm, &mpi->mpisize);
+  SC_CHECK_MPI (mpiret);
+  mpiret = sc_MPI_Comm_rank (mpi->mpicomm, &mpi->mpirank);
+  SC_CHECK_MPI (mpiret);
+
+  sc_init (mpi->mpicomm, 1, 1, NULL, SC_LP_DEFAULT);
+  p4est_init (NULL, SC_LP_DEFAULT);
+
+  /* usage error if the input is not in the correct format */
+  usage =
+    "Arguments: <level>\n"
+    "   Level: controls the maximum depth of refinement\n";
+  wrongusage = 0;
+  if (!wrongusage && argc != 2) {
+    wrongusage = 1;
+  }
+  if (wrongusage) {
+    P4EST_GLOBAL_LERROR (usage);
+    sc_abort_collective ("Usage error");
+  }
+
+  /* assign variables based on configuration */
+  refine_level = atoi (argv[1]);
+
+  /* create connectivity and forest structures */
+  geom = NULL;
+#ifndef P4_TO_P8
+  connectivity = p4est_connectivity_new_bowtie ();
+  p4est = p4est_new_ext (mpi->mpicomm, connectivity, 15, 0, 0,
+                         sizeof (user_data_t), init_fn, geom);
+#else
+  connectivity = p8est_connectivity_new_drop ();
+  p4est = p8est_new_ext (mpi->mpicomm, connectivity, 15, 0, 0,
+                         sizeof (user_data_t), init_fn, geom);
+#endif
+  p4est_vtk_write_file (p4est, geom, "test");
+
+  /* refinement */
+  p4est_refine (p4est, 1, refine_fn, init_fn);
+
+  /* balance */
+  p4est_balance (p4est, P4EST_CONNECT_FULL, init_fn);
+
+  /* partition */
+  p4est_partition (p4est, 0, NULL);
+#ifndef P4_TO_P8
+  p4est_vtk_write_file (p4est, geom, "balance_corner2_partition");
+#else
+  p4est_vtk_write_file (p4est, geom, "balance_corner3_partition");
+#endif
+
+  /* destroy p4est and its connectivity */
+  p4est_destroy (p4est);
+  p4est_connectivity_destroy (connectivity);
+  /* clean up and exit */
+  sc_finalize ();
+
+  mpiret = sc_MPI_Finalize ();
+  SC_CHECK_MPI (mpiret);
+
+  return 0;
+}

example/balance/balance_corner3.c

@@ -0,0 +1,26 @@
+/*
+  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
+  Additional copyright (C) 2011 individual authors
+  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.
+*/
+
+#include <p4est_to_p8est.h>
+#include "balance_corner2.c"

src/p4est_connectivity.h

@@ -32,7 +32,7 @@
  * direction of its x- and y-axes as well as the numbering of its faces and
  * corners.
  * Each tree may connect to any other tree (including itself) across any of
- * its faces and/or edges, where the neighbor may be arbitrarily rotated
+ * its faces and/or corners, where the neighbor may be arbitrarily rotated
  * and/or flipped.
  * The \ref p4est_connectivity data structure stores these connections.
  *
@@ -292,7 +292,7 @@ void                p4est_neighbor_transform_coordinates_reverse
  *
  * \param [in]  conn   Connectivity structure.
  * \param [in]  tree_id The number of the tree.
- * \param [in]  boundary_type  The type of the boundary connection (self, face, corner, edge).
+ * \param [in]  boundary_type  The type of the boundary connection (self, face, corner).
  * \param [in]  boundary_index  The index of the boundary.
  * \param [in,out] neighbor_transform_array   Array of the neighbor transforms.
  */
@@ -660,13 +660,13 @@ p4est_connectivity_t *p4est_connectivity_new_byname (const char *name);
  * than a power of 2.
  *
  * \param [in] conn         A valid connectivity
- * \param [in] num_per_edge The number of new trees in each direction.
+ * \param [in] num_per_dim  The number of new trees in each direction.
  *                      Must use no more than \ref P4EST_OLD_QMAXLEVEL bits.
  *
  * \return a refined connectivity.
  */
 p4est_connectivity_t *p4est_connectivity_refine (p4est_connectivity_t * conn,
-                                                 int num_per_edge);
+                                                 int num_per_dim);
 
 /** Fill an array with the axis combination of a face neighbor transform.
  * \param [in]  iface       The number of the originating face.
@@ -679,7 +679,7 @@ p4est_connectivity_t *p4est_connectivity_refine (p4est_connectivity_t * conn,
  *                          the first referring to the tangential and the second
  *                          to the normal.  A permutation of (0, 1).
  *              [3,5]       The coordinate axis sequence of the target face.
- *              [6,8]       Edge reversal flag for tangential axis (boolean);
+ *              [6,8]       Face reversal flag for tangential axis (boolean);
  *                          face code in [0, 3] for the normal coordinate q:
  *                          0: q' = -q
  *                          1: q' = q + 1
@@ -697,7 +697,8 @@ void                p4est_expand_face_transform (int iface, int nface,
  * \param [out] ftransform    This array holds 9 integers.
  *              [0,2]         The coordinate axis sequence of the origin face.
  *              [3,5]         The coordinate axis sequence of the target face.
- *              [6,8]         Edge reverse flag for axis t; face code for axis n.
+ *              [6,8]         Face reversal flag for axis t; face code for axis n.
+ *                            \see p4est_expand_face_transform.
  *              [1,4,7]       0 (unused for compatibility with 3D).
  * \return                    The face neighbor tree if it exists, -1 otherwise.
  */