Better document an issue of curved boundaries.

diff --git a/include/deal.II/grid/grid_generator.h b/include/deal.II/grid/grid_generator.h
index 4c8e04ab733c435a6d24aac08258fe423a70a9b4..0e5f0f7bd380decdb273284172171f45d0ea7db4 100644 (file)
--- a/include/deal.II/grid/grid_generator.h
+++ b/include/deal.II/grid/grid_generator.h
@@ -651,15 +651,19 @@ namespace GridGenerator
   /**
    * Initialize the given triangulation with several
    * @ref GlossCoarseMesh "coarse mesh cells"
-   * that cover a hyperball, i.e. a circle or a
-   * ball around @p center with given @p radius.
+   * that cover a hyperball, i.e. a circle in 2d or a
+   * ball in 3d, around @p center with given @p radius. The function is
+   * used in step-6.
    *
    * In order to avoid degenerate cells at the boundaries, the circle is
-   * triangulated by five cells, the ball by seven cells. Specifically, these
+   * triangulated by five cells, whereas in 3d the ball is subdivided 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
+   * angle approaching 180 degrees, as opposed to the case where one might
+   * start with just one square (or cube) to approximate the domain.
+   * The diameter of the
    * center cell is chosen so that the aspect ratio of the boundary cells
    * after one refinement is optimized.
    *
@@ -676,10 +680,46 @@ namespace GridGenerator
    * not be the optimal one to create a good a mesh for a hyperball. The
    * "Possibilities for extensions" section of step-6 has an extensive
    * discussion of how one would construct better meshes and what one needs to
-   * do for it. Selecting the argument @p
-   * attach_spherical_manifold_on_boundary_cells to true attaches a
-   * SphericalManifold manifold also to the boundary cells, and not only to the
-   * boundary faces.
+   * do for it. Setting the argument
+   * `attach_spherical_manifold_on_boundary_cells` to true attaches a
+   * SphericalManifold manifold also to the cells adjacent to the boundary, and
+   * not only to the boundary faces.
+   *
+   * @note Since this is likely one of the earliest functions users typically
+   *   consider to create meshes with curved boundaries, let us also comment
+   *   on one aspect that is often confusing: Namely, that what one sees is not
+   *   always what is actually happening. Specifically, if you output the coarse
+   *   mesh with a function such as GridOut::write_vtk() using default options,
+   *   then one doesn't generally get to see curved faces at the boundary.
+   *   That's because most file formats by default only store vertex locations,
+   *   with the implicit understanding that cells are composed from these
+   *   vertices and bounded by straight edges. At the same time, the fact
+   *   that this function attaches a SphericalManifold object to the boundary
+   *   faces means that at least *internally*, edges really are curved. If
+   *   you want to see them that way, you need to make sure that the function
+   *   you use to output the mesh actually plots boundary faces as curved
+   *   lines rather than straight lines characterized by only the locations
+   *   of the two end points. For example, GridOut::write_gnuplot() can do
+   *   that if you set the corresponding flag in the GridOutFlags::Gnuplot
+   *   structure. It is, however, an entirely separate consideration whether
+   *   you are actually *computing* on curved cells. In typical finite
+   *   element computations, one has to compute integrals and these are
+   *   computed by transforming back actual cells using a mapping to the
+   *   reference cell. What mapping is used determines what shape the
+   *   cells have for these internal computations: For example, with the
+   *   widely used $Q_1$ mapping (implicitly used in step-6), integration
+   *   always happens on cells that are assumed to have straight boundaries
+   *   described by only the vertex locations. In other words, if such a
+   *   mapping is used, then the cells of the domain really do have
+   *   straight edges, regardless of the manifold description attached
+   *   to these edges and regardless of the flags given when generating
+   *   output. As a consequence of all of this, it is important to
+   *   distinguish three things: (i) the manifold description attached to an
+   *   object in the mesh; (ii) the mapping used in integration; and (iii) the
+   *   style used in outputting graphical information about the mesh. All of
+   *   these can be chosen more or less independently of each other, and
+   *   what you see visualized is not necessarily exactly what is
+   *   happening.
    *
    * @note The triangulation passed as argument needs to be empty when calling this function.
    */

diff --git a/include/deal.II/grid/grid_out.h b/include/deal.II/grid/grid_out.h
index 656235383403d2e415fff373db26e6d0c7e1de3d..958f06e3c60f9c3a21a8bc21f5b9f242ef682e96 100644 (file)
--- a/include/deal.II/grid/grid_out.h
+++ b/include/deal.II/grid/grid_out.h
@@ -1044,7 +1044,7 @@ public:
    * Write the triangulation in the gnuplot format.
    *
    * In GNUPLOT format, each cell is written as a sequence of its confining
-   * lines. Apart from the coordinates of the line's end points, the level and
+   * lines. Apart from the coordinates of the lines' end points, the level and
    * the material of the cell are appended to each line of output. Therefore,
    * if you let GNUPLOT draw a 2d grid as a 3d plot, you will see more refined
    * cells being raised against cells with less refinement.  Also, if you draw