ScalarField.preimage: Make pullback an alias; expand documentation

src/sage/manifolds/continuous_map.py

@@ -870,6 +870,8 @@ def preimage(self, codomain_subset, name=None, latex_name=None):
         r"""
         Return the preimage of ``codomain_subset`` under ``self``.
 
+        An alias is :meth:`pullback`.
+
         INPUT:
 
         - ``codomain_subset`` -- an instance of

src/sage/manifolds/differentiable/diff_map.py

@@ -844,22 +844,30 @@ def pullback(self, tensor_or_codomain_subset, name=None, latex_name=None):
         r"""
         Pullback operator associated with ``self``.
 
-        In what follows, let `\Phi` denote a differentiable map, `M` its
-        domain and `N` its codomain.
+        In what follows, let `\Phi` denote a differentiable map ``self``,
+        `M` its domain and `N` its codomain.
 
         INPUT:
 
-        - ``tensor`` --
-          :class:`~sage.manifolds.differentiable.tensorfield.TensorField`;
-          a fully covariant tensor field `T` on `N`, i.e. a tensor
-          field of type `(0, p)`, with `p` a positive or zero integer; the
-          case `p = 0` corresponds to a scalar field
+        One of the following:
+
+        - ``tensor_or_codomain_subset`` -- one of the following:
+
+          - a :class:`~sage.manifolds.differentiable.tensorfield.TensorField`;
+            a fully covariant tensor field `T` on `N`, i.e. a tensor
+            field of type `(0, p)`, with `p` a positive or zero integer; the
+            case `p = 0` corresponds to a scalar field
+          - a :class:`~sage.manifolds.subset.ManifoldSubset` `S`
 
         OUTPUT:
 
-        - a :class:`~sage.manifolds.differentiable.tensorfield.TensorField`
+        - (if the input is a tensor field `T`)
+          a :class:`~sage.manifolds.differentiable.tensorfield.TensorField`
           representing a fully covariant tensor field on `M` that is the
           pullback of `T` by `\Phi`
+        - (if the input is a manifold subset `S`)
+          a :class:`~sage.manifolds.subset.ManifoldSubset` that is the
+          preimage `\Phi^{-1}(S)`; same as :meth:`preimage`
 
         EXAMPLES:
 

src/sage/manifolds/scalarfield.py

@@ -2546,10 +2546,25 @@ def __call__(self, p, chart=None):
                              "the action of {} on the {}".format(self, p))
         return self._express[chart](*(p._coordinates[chart]))
 
-    def pullback(self, codomain_subset, name=None, latex_name=None):
+    def preimage(self, codomain_subset, name=None, latex_name=None):
         """
         Return the preimage of ``codomain_subset``.
 
+        An alias is :meth:`pullback`.
+
+        INPUT:
+
+        - ``codomain_subset`` -- an instance of
+          :class:`~sage.manifolds.subset.ManifoldSubset`
+        - ``name`` -- string; name (symbol) given to the subset
+        - ``latex_name`` --  (default: ``None``) string; LaTeX symbol to
+          denote the subset; if none are provided, it is set to ``name``
+
+        OUTPUT:
+
+        - an instance of
+          :class:`~sage.manifolds.subsets.pullback.ManifoldSubsetPullback`
+
         EXAMPLES::
 
             sage: M = Manifold(2, 'M', structure='topological')
@@ -2566,6 +2581,8 @@ def pullback(self, codomain_subset, name=None, latex_name=None):
         return ManifoldSubsetPullback(self, codomain_subset=codomain_subset,
                                       name=name, latex_name=latex_name)
 
+    pullback = preimage
+
     def __pos__(self):
         r"""
         Unary plus operator.

src/sage/manifolds/subsets/pullback.py

@@ -37,12 +37,11 @@ class ManifoldSubsetPullback(ManifoldSubset):
 
     INPUT:
 
-    - ``map`` - an instance of :class:`ContinuousMap` or
-      :class:`ScalarField` or :class:`Chart`
+    - ``map`` - an instance of :class:`ContinuousMap`,
+      :class:`ScalarField`, or :class:`Chart`
 
     - ``codomain_subset`` - an instance of :class:`~sage.manifolds.subset.ManifoldSubset`,
-      :class:`RealSet`, :class:`Polyhedron_base`,
-      :class:`C_Polyhedron`, :class:`NNC_Polyhedron`
+      :class:`RealSet`, or :class:`~sage.geometry.convex_set.ConvexSet_base`
 
     EXAMPLES::
 
@@ -504,7 +503,8 @@ def _coord_def(map, codomain_subset):
 
         OUTPUT:
 
-        - an object suitable for the parameter ``coord_def`` of :meth:`TopologicalManifold.open_subset`.
+        - an object suitable for the parameter ``coord_def`` of
+          :meth:`sage.manifolds.manifold.TopologicalManifold.open_subset`.
 
         EXAMPLES::
 
@@ -697,9 +697,9 @@ def is_open(self):
         ``codomain_subset`` is open.
 
         However, the design of :class:`~sage.manifolds.subset.ManifoldSubset` requires that open subsets
-        are instances of the subclass :class:`TopologicalManifold`.
+        are instances of the subclass :class:`sage.manifolds.manifold.TopologicalManifold`.
         The constructor of :class:`ManifoldSubsetPullback` delegates to a subclass
-        of :class:`TopologicalManifold` for some open subsets.
+        of :class:`sage.manifolds.manifold.TopologicalManifold` for some open subsets.
 
         EXAMPLES::