Documentation of GridGenerator::cylinder() incomplete and incorrect.

[nfehn]

1. The documentation of GridGenerator::cylinder() (https://www.dealii.org/current/doxygen/deal.II/namespaceGridGenerator.html#a5cdda7b4a76d509af7d1a8dc1320ddb0)
   does not give information on how many elements are used in axial direction. It would make sense to extend the implementation so that the number of axial cells becomes a parameter of this function. No information is given how the 2D mesh looks like.

2. The documentation further says

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.

This point is closely related to issue #8914, but is written here separately as things seem to become complicated.

Let's test the manifold first:

  double const r = 0.5, L = 1.5;
  GridGenerator::cylinder(*triangulation, r, L);
  triangulation->refine_global(2);

Let's now apply a simple transformation on top

  double const r = 0.5, L = 1.5;
  GridGenerator::cylinder(*triangulation, r, L);
  Transformation<dim> transformation;
  GridTools::transform(transformation, *triangulation);
  triangulation->refine_global(2);

with transformation

template<int dim>
class Transformation
{
public:

  Point<dim> operator()(Point<dim> &x_in) const
  {
    Point<dim> x_out;

    for(unsigned int d=0; d<dim; ++d)
      x_out[d] = x_in[d] + 1.0;

    return x_out;
  }
};

resulting in

In terms of documentation only, the main problem is that the documentation insinuates that CylinderManifold and GridTools::transform() are compatible. The correct behavior of functions of this type are discussed elsewhere in #8914, but here I want to point out that the documentation should not promise more than the software can offer.

Playing around with the offset of the transformation (1.0 in the example above), you can obtain a nice heart-like geometry ;)

One might now argue with some experience that one first needs to refine before applying GridTools::transform(), i.e.,

  double const r = 0.5, L = 1.5;
  GridGenerator::cylinder(*triangulation, r, L);
  triangulation->refine_global(2);
  Transformation<dim> transformation;
  GridTools::transform(transformation, *triangulation);

resulting in (offset = 0.5)

So one needs to explicitly deactivate the manifold in addition (see issue #8914)

  double const r = 0.5, L = 1.5;
  GridGenerator::cylinder(*triangulation, r, L);
  triangulation->refine_global(2);
  triangulation->reset_all_manifolds();
  Transformation<dim> transformation;
  GridTools::transform(transformation, *triangulation);

so that we get at least a cylinder with linear approximation of the boundary

Unfortunately, this is not what the documentation suggests, since the documentation of GridTools::transform() (https://www.dealii.org/current/doxygen/deal.II/namespaceGridTools.html#a212e99cf0d923cebfa04f1d23fa60b04) says

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.

[bangerth]

The problem with the documentation here is that it predates the time when we attached manifolds to all parts of the geometries generated by GridGenerator. In other words, when the documentation was written, the geometry created was using default (=straight) manifolds for all parts of the mesh, and those were allowed when used with GridTools::transform(). But now that we use manifolds, we also need to transform these manifolds and that's a much more difficult enterprise of course.

You are of course entirely correct that that should be addressed in the documentation!