Improve documentation of classes Chart and ContinuousMap

Author: egourgoulhon

src/sage/manifolds/chart.py

@@ -50,8 +50,8 @@ class Chart(UniqueRepresentation, SageObject):
     an open subset `V` of `K^n`.
 
     The components `(x^1,\ldots,x^n)` of `\varphi`, defined by
-    `\varphi(p) = (x^1(p),\ldots,x^n(p))`, are called the *coordinates* of the
-    chart `(U,\varphi)`.
+    `\varphi(p) = (x^1(p),\ldots,x^n(p))\in K^n` for any point `p\in U`,
+    are called the *coordinates* of the chart `(U,\varphi)`.
 
     INPUT:
 
@@ -1051,8 +1051,8 @@ class RealChart(Chart):
     an open subset `V` of `\RR^n`.
 
     The components `(x^1,\ldots,x^n)` of `\varphi`, defined by
-    `\varphi(p) = (x^1(p),\ldots,x^n(p))`, are called the *coordinates* of the
-    chart `(U,\varphi)`.
+    `\varphi(p) = (x^1(p),\ldots,x^n(p))\in \RR^n` for any point `p\in U`,
+    are called the *coordinates* of the chart `(U,\varphi)`.
 
     INPUT:
 

src/sage/manifolds/continuous_map.py

@@ -50,9 +50,6 @@ class ContinuousMap(Morphism):
     where `M` and `N` are topological manifolds over the same topological
     field `K`, `U` is an open subset of `M` and `V` is an open subset of `N`.
 
-    In what follows, `M` is called the *start manifold* and
-    `N` the *arrival manifold*.
-
     Continuous maps are the *morphisms* of the *category* of
     topological manifolds. The set of all continuous maps from
     `U` to `V` is therefore the homset between `U` and `V` and is denoted
@@ -70,7 +67,7 @@ class is :class:`~sage.manifolds.manifold_homset.TopManifoldHomset`.
       coordinates of the image expressed in terms of the coordinates of
       the considered point) with the pairs of charts (chart1, chart2)
       as keys (chart1 being a chart on `U` and chart2 a chart on `V`).
-      If the dimension of the arrival manifold is 1, a single coordinate
+      If the dimension of the map's codomain is 1, a single coordinate
       expression can be passed instead of a tuple with a single element
     - ``name`` -- (default: ``None``) name given to the continuous map
     - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the
@@ -214,7 +211,7 @@ class is :class:`~sage.manifolds.manifold_homset.TopManifoldHomset`.
         on U: (x, y) |--> (xP, yP) = (x, y)
         on V: (u, v) |--> (xP, yP) = (u/(u^2 + v^2), v/(u^2 + v^2))
 
-    If the arrival manifold is 1-dimensional, a continuous map must be
+    If its codomain is 1-dimensional, a continuous map must be
     defined by a single symbolic expression for each pair of charts, and not
     by a list/tuple with a single element::
 
@@ -912,7 +909,7 @@ def display(self, chart1=None, chart2=None):
         INPUT:
 
         - ``chart1`` -- (default: ``None``) chart on the map's domain; if ``None``,
-          the display is performed on all the charts on the start manifold
+          the display is performed on all the charts on the domain
           in which the map is known or computable via some change of
           coordinates
         - ``chart2`` -- (default: ``None``) chart on the map's codomain; if
@@ -953,7 +950,7 @@ def display(self, chart1=None, chart2=None):
             \begin{array}{llcl} \Phi:& S^2 & \longrightarrow & \RR^3 \\ \mbox{on}\ U : & \left(x, y\right) & \longmapsto & \left(X, Y, Z\right) = \left(\frac{2 \, x}{x^{2} + y^{2} + 1}, \frac{2 \, y}{x^{2} + y^{2} + 1}, \frac{x^{2} + y^{2} - 1}{x^{2} + y^{2} + 1}\right) \end{array}
 
         If the argument ``chart2`` is not specified, the display is performed
-        on all the charts on the arrival manifold in which the map is known
+        on all the charts on the codomain in which the map is known
         or computable via some change of coordinates (here only one chart:
         c_cart)::
 
@@ -962,7 +959,7 @@ def display(self, chart1=None, chart2=None):
             on U: (x, y) |--> (X, Y, Z) = (2*x/(x^2 + y^2 + 1), 2*y/(x^2 + y^2 + 1), (x^2 + y^2 - 1)/(x^2 + y^2 + 1))
 
         Similarly, if the argument ``chart1`` is omitted, the display is
-        performed on all the charts on the start manifold in which the
+        performed on all the charts on the map's domain in which the
         map is known or computable via some change of coordinates::
 
             sage: Phi.display(chart2=c_cart)
@@ -1191,8 +1188,8 @@ def coord_functions(self, chart1=None, chart2=None):
                     change_arrival.append(ochart2)
                 if chart2 == ochart2:
                     change_start.append(ochart1)
-            # 1/ Trying to make a change of chart only on the arrival domain:
-            # the arrival default chart is privileged:
+            # 1/ Trying to make a change of chart only on the codomain:
+            # the codomain's default chart is privileged:
             sel_chart2 = None # selected chart2
             if def_chart2 in change_arrival \
                     and (def_chart2, chart2) in dom2._coord_changes:
@@ -1210,7 +1207,7 @@ def coord_functions(self, chart1=None, chart2=None):
                 return self._coord_expression[(chart1, chart2)]
 
             # 2/ Trying to make a change of chart only on the start domain:
-            # the start default chart is privileged:
+            # the domain's default chart is privileged:
             sel_chart1 = None # selected chart1
             if def_chart1 in change_start \
                     and (chart1, def_chart1) in dom1._coord_changes:
@@ -1358,7 +1355,7 @@ def set_expr(self, chart1, chart2, coord_functions):
         - ``coord_functions`` -- the coordinate symbolic expression of the
           map in the above charts: list (or tuple) of the coordinates of
           the image expressed in terms of the coordinates of the considered
-          point; if the dimension of the arrival manifold is 1, a single
+          point; if the dimension of the codomain is 1, a single
           expression is expected (not a list with a single element)
 
         EXAMPLES:
@@ -1450,7 +1447,7 @@ def add_expr(self, chart1, chart2, coord_functions):
         - ``coord_functions`` -- the coordinate symbolic expression of the
           map in the above charts: list (or tuple) of the coordinates of
           the image expressed in terms of the coordinates of the considered
-          point; if the dimension of the arrival manifold is 1, a single
+          point; if the dimension of the codomain is 1, a single
           expression is expected (not a list with a single element)
 
         .. WARNING::
@@ -1728,6 +1725,36 @@ def __invert__(self):
             sage: ~rot is rot.inverse()
             True
 
+        An example with multiple charts: the equatorial symmetry on the
+        2-sphere::
+
+            sage: M = TopManifold(2, 'M') # the 2-dimensional sphere S^2
+            sage: U = M.open_subset('U') # complement of the North pole
+            sage: c_xy.<x,y> = U.chart() # stereographic coordinates from the North pole
+            sage: V = M.open_subset('V') # complement of the South pole
+            sage: c_uv.<u,v> = V.chart() # stereographic coordinates from the South pole
+            sage: M.declare_union(U,V)   # S^2 is the union of U and V
+            sage: xy_to_uv = c_xy.transition_map(c_uv, (x/(x^2+y^2), y/(x^2+y^2)), \
+                                                 intersection_name='W', restrictions1= x^2+y^2!=0, \
+                                                 restrictions2= u^2+v^2!=0)
+            sage: uv_to_xy = xy_to_uv.inverse()
+            sage: s = M.homeomorphism(M, {(c_xy, c_uv): [x, y], (c_uv, c_xy): [u, v]}, name='s')
+            sage: s.display()
+            s: M --> M
+            on U: (x, y) |--> (u, v) = (x, y)
+            on V: (u, v) |--> (x, y) = (u, v)
+            sage: si = s.inverse(); si
+            Homeomorphism s^(-1) of the 2-dimensional topological manifold M
+            sage: si.display()
+            s^(-1): M --> M
+            on U: (x, y) |--> (u, v) = (x, y)
+            on V: (u, v) |--> (x, y) = (u, v)
+
+        The equatorial symmetry is of course an involution::
+
+            sage: si == s
+            True
+
         """
         from sage.symbolic.ring import SR
         from sage.symbolic.relation import solve

src/sage/manifolds/manifold.py

@@ -1231,25 +1231,26 @@ def open_subset(self, name, latex_name=None, coord_def={}):
 
     def chart(self, coordinates='', names=None):
         r"""
-        Define a chart the domain of which is the manifold.
+        Define a chart, the domain of which is the manifold.
 
         A *chart* is a pair `(U,\varphi)`, where `U` is the current manifold
         and `\varphi: U \rightarrow V \subset K^n`
         is a homeomorphism from `U` to an open subset `V` of `K^n`, `K` being
-        the field on which the manifold containing the open set is defined.
+        the field on which the manifold is defined.
 
         The components `(x^1,\ldots,x^n)` of `\varphi`, defined by
-        `\varphi(p) = (x^1(p),\ldots,x^n(p))`, are called the *coordinates*
-        of the chart `(U,\varphi)`.
+        `\varphi(p) = (x^1(p),\ldots,x^n(p))\in K^n` for any point `p\in U`,
+        are called the *coordinates* of the chart `(U,\varphi)`.
 
         See :class:`~sage.manifolds.chart.Chart` for a complete
         documentation.
 
         INPUT:
 
-        - ``coordinates`` -- single string defining the coordinate symbols and
-          ranges: the coordinates are separated by ' ' (space) and each
-          coordinate has at most three fields, separated by ':':
+        - ``coordinates`` --  (default: '' (empty string)) single string
+          defining the coordinate symbols and ranges: the coordinates are
+          separated by ' ' (space) and each coordinate has at most three fields,
+          separated by ':':
 
           1. The coordinate symbol (a letter or a few letters)
           2. (optional, only for manifolds over `\RR`) The interval `I`
@@ -1261,8 +1262,8 @@ def chart(self, coordinates='', names=None):
              (a,b] (or equivalently ]a,b]) are allowed.
              Note that the interval declaration must not contain any space
              character.
-          3. (optional) The LaTeX spelling of the coordinate; if not provided the
-             coordinate symbol given in the first field will be used.
+          3. (optional) The LaTeX spelling of the coordinate; if not provided
+             the coordinate symbol given in the first field will be used.
 
           The order of the fields 2 and 3 does not matter and each of them can
           be omitted.
@@ -1271,11 +1272,12 @@ def chart(self, coordinates='', names=None):
           treatment of the backslash character (see examples below).
           If no interval range and no LaTeX spelling is to be provided for any
           coordinate, the argument ``coordinates`` can be omitted when the
-          shortcut operator <,> is used via Sage preparser (see examples below)
+          shortcut operator ``<,>`` is used via Sage preparser (see examples
+          below)
         - ``names`` -- (default: ``None``) unused argument, except if
           ``coordinates`` is not provided; it must then be a tuple containing
-          the coordinate symbols (this is guaranted if the shortcut operator <,>
-          is used).
+          the coordinate symbols (this is guaranted if the shortcut operator
+          ``<,>`` is used).
 
         OUTPUT:
 
@@ -1383,8 +1385,8 @@ def scalar_field(self, coord_expression=None, chart=None, name=None,
         r"""
         Define a scalar field on the manifold.
 
-        See :class:`~sage.manifolds.scalarfield.ScalarField` for a
-        complete documentation.
+        See :class:`~sage.manifolds.scalarfield.ScalarField` for a complete
+        documentation.
 
         INPUT: