Update documentation around hyper-balls and spherical manifolds.

In particular, link to the discussion in the results section of step-6.

diff --git a/examples/step-6/doc/results.dox b/examples/step-6/doc/results.dox
index da72f27fa9eb061d61bd6e869663050bcd9deb4e..5f9025baffbe489a2cdb8425d25ee2d4401efe09 100644 (file)
--- a/examples/step-6/doc/results.dox
+++ b/examples/step-6/doc/results.dox
@@ -292,7 +292,7 @@ vertices at the edge midpoints and the cell midpoint be located so that the
 child cells better represent the desired geometry than the parent cell.
 
 In the code above, we already do this for faces that sit at the boundary:
-we use the code
+There, we use the code
 @code
           static const SphericalManifold<dim> boundary;
           triangulation.set_all_manifold_ids_on_boundary(0);

diff --git a/include/deal.II/grid/grid_generator.h b/include/deal.II/grid/grid_generator.h
index cbfc1f1ebe076446733d2d8d32ad34086707bf78..946a84646bfa25d433a5c6b8c0dbf358975b25d6 100644 (file)
--- a/include/deal.II/grid/grid_generator.h
+++ b/include/deal.II/grid/grid_generator.h
@@ -436,11 +436,16 @@ namespace GridGenerator
                             const bool          colorize = false);
 
   /**
-   * Initialize the given triangulation with a hyperball, i.e. a circle or a
+   * Initialize the given triangulation with several coarse mesh cells
+   * that cover a hyperball, i.e. a circle or a
    * ball around @p center with given @p radius.
    *
    * In order to avoid degenerate cells at the boundaries, the circle is
-   * triangulated by five cells, the ball by seven cells. The diameter of the
+   * triangulated by five cells, the ball by seven cells. Specifically, these
+   * cells are one cell in the center plus one "cap" cell on each of the faces
+   * of this center cell. This ensures that under repeated refinement, none
+   * of the cells at the outer boundary will degenerate to have an interior
+   * angle approaching 180 degrees. The diameter of the
    * center cell is chosen so that the aspect ratio of the boundary cells
    * after one refinement is optimized.
    *
@@ -449,7 +454,11 @@ namespace GridGenerator
    *
    * You should attach a SphericalManifold to the cells and faces for correct
    * placement of vertices upon refinement and to be able to use higher order
-   * mappings.
+   * mappings. However, it turns out that creating a mesh for a hyperball is
+   * not entirely trivial since the central cell has to be treated
+   * differently than the "cap" cells. The "Possibilities for extensions"
+   * section of step-6 has an extensive discussion of how one would construct
+   * such meshes and what one needs to do for it.
    *
    * @note The triangulation passed as argument needs to be empty when calling this function.
    */

diff --git a/include/deal.II/grid/manifold_lib.h b/include/deal.II/grid/manifold_lib.h
index 1392896a3c8c5d2e785a45a6833cad2c97ead387..7dd30ffc5ddd5b3a3f4dc68580dc3c92987f6bda 100644 (file)
--- a/include/deal.II/grid/manifold_lib.h
+++ b/include/deal.II/grid/manifold_lib.h
@@ -127,7 +127,14 @@ private:
  * spherical surface embedded in a higher dimensional space, or as a
  * co-dimension zero manifold descriptor for a body with positive
  * volume, provided that the center of the spherical space is excluded
- * from the domain.
+ * from the domain. An example for the use of this function would be
+ * in the description of a hyper-shell or hyper-ball geometry, for
+ * example after creating a coarse mesh using GridGenerator::hyper_ball().
+ * (However, it is worth mentioning that generating a good mesh for
+ * a disk or ball is complicated and requires addition steps. See the
+ * "Possibilities for extensions" section of step-6 for an extensive
+ * discussion of how one would construct such meshes and what one
+ * needs to do for it.)
  *
  * The two template arguments match the meaning of the two template arguments
  * in Triangulation<dim, spacedim>, however this Manifold can be used to