From f620e989c6b2d5650a7e56ffba0623934fdeb9ca Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Thu, 27 Jan 2022 13:25:36 -0700 Subject: [PATCH] Minor updates to the documentation of GridTools::transform(). --- include/deal.II/grid/grid_tools.h | 47 ++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h index ea340ebe04..7b117ccac0 100644 --- a/include/deal.II/grid/grid_tools.h +++ b/include/deal.II/grid/grid_tools.h @@ -480,8 +480,9 @@ namespace GridTools * The transformation given as argument is used to transform each vertex. * Its respective type has to offer a function-like syntax, i.e. the * predicate is either an object of a type that has an operator(), - * or it is a pointer to the function. In either case, argument and return - * value have to be of type Point@. + * or it is a pointer to a non-member function, or it is a lambda function + * object. In either case, argument and return + * value have to be of type `Point@`. * * @note The transformations that make sense to use with this function * should have a Jacobian with a positive determinant. For example, @@ -506,20 +507,28 @@ namespace GridTools * 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 + * does not hold in general, and it is necessary to clear manifolds from + * the triangulation (for example, using Triangulation::clear_all_manifolds()) + * before the transformation, and then attach new ones after the + * transformation that are valid for the transformed geometry. There are cases + * where this is awkward, most notably if you are using a mesh generated by + * the functions in GridGenerator which generally attach suitable manifolds + * upon mesh generation; in those cases, you will have to think about how + * these manifolds were constructed, and create a manifold that is constructed + * in a similar way but applies to the transformed geometry. As a consequence, + * if you only care about manifolds for mesh refinement, it is often simpler + * to just refine the original mesh before transformation as needed, and then + * simply forget about the manifolds. Of course, manifolds are also used for + * other cases (e.g., for normal vectors, curved edges and faces, and higher + * order mappings), and if these are relevant to what you are doing, then + * there is no alternative to building appropriate manifolds for the + * transformed geometry and attaching these to the transformed geometry. In + * general, detaching manifolds from a triangulation and then doing the + * transformation would look as follows: * @code * ... - * triangulation.refine_global(n_refinements); * triangulation.reset_all_manifolds(); - * Transformation transformation; - * GridTools::transform(transformation, triangulation); + * GridTools::transform(MyTransformation(), triangulation); * ... * @endcode * @@ -534,7 +543,8 @@ namespace GridTools /** * Shift each vertex of the triangulation by the given shift vector. This * function uses the transform() function above, so the requirements on the - * triangulation stated there hold for this function as well. + * triangulation stated there hold for this function as well; in particular, + * this is true about the discussion about manifolds. */ template void @@ -547,7 +557,8 @@ namespace GridTools * counter-clockwise sense around the origin of the coordinate system by the * given angle (given in radians, rather than degrees). This function uses * the transform() function above, so the requirements on the triangulation - * stated there hold for this function as well. + * stated there hold for this function as well; in particular, + * this is true about the discussion about manifolds. * * @note This function is only supported for dim=2. */ @@ -558,7 +569,8 @@ namespace GridTools /** * Rotate all vertices of the given @p triangulation in counter-clockwise * direction around the @p axis described by a unit vector. Otherwise like the - * function above. + * function above; in particular, this function calls the transform() function + * and so the discussion about manifolds there also applies here. * * @param[in] angle Angle in radians to rotate the Triangulation by. * @param[in] axis A unit vector that defines the axis of rotation. @@ -575,7 +587,8 @@ namespace GridTools /** * Rotate all vertices of the given @p triangulation in counter-clockwise * direction around the axis with the given index. Otherwise like the - * function above. + * function above; in particular, this function calls the transform() function + * and so the discussion about manifolds there also applies here. * * @param[in] angle Angle in radians to rotate the Triangulation by. * @param[in] axis Index of the coordinate axis to rotate around, keeping -- 2.39.5