immersed mesh documentation (#4052)

* immersed mesh documentation

docs/source/mesh-coordinates.rst

@@ -83,6 +83,30 @@ Or simply:
 
    new_mesh = Mesh(Function(f))
 
+Immersing a mesh in higher dimensional space
+--------------------------------------------
+
+A useful special case of creating a mesh on modified coordinates is to immerse
+a lower dimensional mesh in a higher dimension, for example to create a mesh of
+a two-dimensional manifold immersed in 3D.
+
+This is accomplished by setting the value dimension of the new
+:py:func:`~.VectorFunctionSpace` to that of the space in which it should be
+immersed. For example, a mesh of square bent into a sine wave using
+linear (flat) elements can be created with:
+
+.. literalinclude:: ../../tests/firedrake/regression/test_mesh_generation.py
+   :language: python3
+   :dedent:
+   :start-after: start_immerse
+   :end-before: end_immerse
+
+
+.. figure:: images/sin_mesh.png
+  :align: center
+
+  A sine-wave shaped triangle mesh immersed in three-dimensional space.
+
 
 Replacing the mesh geometry of an existing function
 ---------------------------------------------------

tests/firedrake/regression/test_mesh_generation.py

@@ -520,3 +520,18 @@ def test_split_comm_dm_mesh():
     bad_comm = COMM_WORLD.Split(color=(rank % nspace), key=rank)
     with pytest.raises(ValueError):
         mesh2 = Mesh(dm, comm=bad_comm)  # noqa: F841
+
+
+def test_immerse_mesh():
+    """This test exists to ensure that the code used in the manual runs
+    correctly."""
+
+    # start_immerse
+    mesh = UnitSquareMesh(10, 10)
+    x, y = SpatialCoordinate(mesh)
+    coord_fs = VectorFunctionSpace(mesh, "CG", 1, dim=3)
+    new_coord = assemble(interpolate(as_vector([x, y, sin(2*pi*x)]), coord_fs))
+    new_mesh = Mesh(new_coord)
+    # end_immerse
+
+    new_mesh  # Variable reference to silence linter.