From: Niklas Fehn <fehn@lnm.mw.tum.de>
Date: Fri, 8 May 2020 05:47:15 +0000 (+0200)
Subject: correct docu of GridTools::transform() and GridGenerator::cylinder()
X-Git-Tag: v9.2.0-rc1~80^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cd25e8634e7f9340b09b1246ea572698a7e6fdd6;p=dealii.git

correct docu of GridTools::transform() and GridGenerator::cylinder()
---

diff --git a/include/deal.II/grid/grid_generator.h b/include/deal.II/grid/grid_generator.h
index 3171127d8a..36a1ff9133 100644
--- a/include/deal.II/grid/grid_generator.h
+++ b/include/deal.II/grid/grid_generator.h
@@ -837,11 +837,6 @@ namespace GridGenerator
    * face (see
    * @ref GlossColorization "the glossary entry on colorization").
    *
-   * If you want the cylinder to revolve around a different axis than the
-   * $x$-axis, then simply rotate the mesh generated by this function using
-   * the GridTools::transform() function using a rotation operator as
-   * argument.
-   *
    * The manifold id for the hull of the cylinder is set to zero, and a
    * CylindricalManifold is attached to it.
    *
diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index 994a1bedc5..2f4ade51a0 100644
--- a/include/deal.II/grid/grid_tools.h
+++ b/include/deal.II/grid/grid_tools.h
@@ -425,9 +425,28 @@ namespace GridTools
    * hanging nodes in ghost cells if you call the current functions: The
    * vertices of all locally owned cells will be correct, but the vertices of
    * some ghost cells may not. This means that computations like
-   * KellyErrorEstimator may give wrong answers. A safe approach is to use
-   * this function prior to any refinement in parallel, if that is possible,
-   * but not after you refine the mesh.
+   * KellyErrorEstimator may give wrong answers.
+   *
+   * @note This function is in general not compatible with manifolds attached
+   * to the triangulation. For example, in order to refine the grid (using
+   * manifolds) after the grid transformation, you have to make sure that
+   * the original manifold is still valid for the transformed geometry. This
+   * does not hold in general, and it is necessary to clear the manifold and
+   * attach a new one for the transformed geometry in these cases.
+   * If you want to perform refinements according to the original
+   * manifold description attached to the triangulation, you should first do
+   * the refinements, subsequently deactivate all manifolds, and finally call
+   * the transform() function. The result is a triangulation with correctly
+   * transformed vertices, but otherwise straight-sided elements. The
+   * following procedure is recommended
+   * @code
+   * ...
+   * triangulation.refine_global(n_refinements);
+   * triangulation.reset_all_manifolds();
+   * Transformation<dim> transformation;
+   * GridTools::transform(transformation, triangulation);
+   * ...
+   * @endcode
    *
    * This function is used in the "Possibilities for extensions" section of
    * step-38. It is also used in step-49 and step-53.