From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Sun, 7 Apr 2024 22:31:53 +0000 (-0600)
Subject: Update documentation for GridTools::distort_random().
X-Git-Tag: v9.6.0-rc1~388^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F16870%2Fhead;p=dealii.git

Update documentation for GridTools::distort_random().

In particular also remove a reference to the function in the documentation of class
Triangulation. The function used to be part of that class, but has not been for a long
time.
---

diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index 5fc2e5dfd0..a7bed3b3a8 100644
--- a/include/deal.II/grid/grid_tools.h
+++ b/include/deal.II/grid/grid_tools.h
@@ -371,7 +371,16 @@ namespace GridTools
    * vertices of the grid.  The direction of movement of each vertex is
    * random, while the length of the shift vector has a value of @p factor
    * times the minimal length of the active edges adjacent to this vertex.
-   * Note that @p factor should obviously be well below <tt>0.5</tt>.
+   * Note that @p factor should obviously be well below <tt>0.5</tt> in order
+   * to avoid getting cells that are @ref GlossDistorted "distorted".
+   *
+   * The function will make sure that vertices on restricted faces
+   * (i.e., faces with hanging nodes) will end up in the correct
+   * place, i.e. in the middle of the two other vertices of the parent
+   * edge, and the analogue in higher space dimensions (vertices on
+   * the boundary are not corrected, so don't distort boundary
+   * vertices in more than two space dimensions, i.e. in dimensions
+   * where boundary vertices can be hanging nodes).
    *
    * If @p keep_boundary is set to @p true (which is the default), then
    * boundary vertices are not moved.
@@ -381,9 +390,10 @@ namespace GridTools
    * previous versions of deal.II.
    *
    * @note If the Triangulation is of distributed kind (derived from
-   * DistributedTriangulationBase) and computations are done in
+   * parallel::DistributedTriangulationBase) and computations are done in
    * parallel, the new vertex locations will be consistently updated
    * on all ranks.
+   *
    */
   template <int dim, int spacedim>
   void
diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h
index 58e08424b2..9f5165b75a 100644
--- a/include/deal.II/grid/tria.h
+++ b/include/deal.II/grid/tria.h
@@ -774,26 +774,6 @@ namespace internal
  * data will have to be transferred between the grids.
  * </ul>
  *
- * Finally, there is a special function for folks who like bad grids:
- * distort_random(). It moves all the vertices in the grid a bit around by a
- * random value, leaving behind a distorted mesh. Note that you should apply
- * this function to the final mesh, since refinement smoothes the mesh a bit.
- *
- * The function will make sure that vertices on restricted faces (hanging
- * nodes) will end up in the correct place, i.e. in the middle of the two
- * other vertices of the mother line, and the analogue in higher space
- * dimensions (vertices on the boundary are not corrected, so don't distort
- * boundary vertices in more than two space dimension, i.e. in dimensions
- * where boundary vertices can be hanging nodes). Applying the algorithm has
- * another drawback related to the placement of cells, however: the children
- * of a cell will not occupy the same region of the domain as the mother cell
- * does. While this is the usual behavior with cells at the boundary, here you
- * may get into trouble when using multigrid algorithms or when transferring
- * solutions from coarse to fine grids and back. In general, the use of this
- * function is only safe if you only use the most refined level of the
- * triangulation for computations.
- *
- *
  *
  * <h3>Refinement and coarsening of a triangulation</h3>
  *