Trac #30799: Add Folder for Manifold Examples

Belongs to #30189.

I propose to add a new folder for manifold examples:

`src/sage/manifolds/differentiable/examples`

Furthermore, I suggest we move `euclidean.py` and `real_line.py` to that
folder and make it, besides the global availability, accessible from the
catalog, too. The idea is that any manifold example can be accessed via
the catalog, and the corresponding files are stored in the `examples`
folder.

For manifolds with non-smooth structure (or non-diffeomorphic
structures), we can add such a folder in `manifolds`, too. But I don't
see the need yet.

URL: https://trac.sagemath.org/30799
Reported by: gh-mjungmath
Ticket author(s): Michael Jung
Reviewer(s): Travis Scrimshaw

Author: Release Manager

src/doc/en/reference/euclidean_spaces/index.rst

@@ -6,6 +6,6 @@ Euclidean Spaces and Vector Calculus
 .. toctree::
    :maxdepth: 2
 
-   sage/manifolds/differentiable/euclidean
+   sage/manifolds/differentiable/examples/euclidean
 
    sage/manifolds/operators

src/doc/en/reference/manifolds/diff_manifold.rst

@@ -8,7 +8,7 @@ Differentiable Manifolds
 
    sage/manifolds/differentiable/chart
 
-   sage/manifolds/differentiable/real_line
+   sage/manifolds/differentiable/examples/real_line
 
    diff_scalarfield
 

src/doc/en/reference/manifolds/euclidean_space.rst

@@ -6,6 +6,6 @@ Euclidean Spaces and Vector Calculus
 .. toctree::
    :maxdepth: 2
 
-   sage/manifolds/differentiable/euclidean
+   sage/manifolds/differentiable/examples/euclidean
 
    sage/manifolds/operators

src/sage/manifolds/all.py

@@ -1,6 +1,6 @@
 from sage.misc.lazy_import import lazy_import
 lazy_import('sage.manifolds.manifold', 'Manifold')
-lazy_import('sage.manifolds.differentiable.real_line', 'OpenInterval')
-lazy_import('sage.manifolds.differentiable.real_line', 'RealLine')
-lazy_import('sage.manifolds.differentiable.euclidean', 'EuclideanSpace')
-import sage.manifolds.catalog as manifolds
+lazy_import('sage.manifolds.differentiable.examples.real_line', 'OpenInterval')
+lazy_import('sage.manifolds.differentiable.examples.real_line', 'RealLine')
+lazy_import('sage.manifolds.differentiable.examples.euclidean', 'EuclideanSpace')
+lazy_import('sage.manifolds', 'catalog', 'manifolds')

src/sage/manifolds/catalog.py

@@ -7,6 +7,9 @@
 ``manifolds.<tab>``, where ``<tab>`` indicates pressing the tab key.
 They are:
 
+- :class:`~sage.manifolds.differentiable.examples.euclidean.EuclideanSpace`: Euclidean space
+- :class:`~sage.manifolds.differentiable.examples.real_line.RealLine`: real line
+- :class:`~sage.manifolds.differentiable.examples.real_line.OpenInterval`: open interval on the real line
 - :func:`Sphere`: sphere embedded in Euclidean space
 - :func:`Torus`: torus embedded in Euclidean space
 - :func:`Minkowski`: 4-dimensional Minkowski space
@@ -27,6 +30,12 @@
 #                  http://www.gnu.org/licenses/
 # *****************************************************************************
 
+# Lazy import from examples folders:
+from sage.misc.lazy_import import lazy_import as _lazy_import
+_lazy_import('sage.manifolds.differentiable.examples.real_line', 'OpenInterval')
+_lazy_import('sage.manifolds.differentiable.examples.real_line', 'RealLine')
+_lazy_import('sage.manifolds.differentiable.examples.euclidean', 'EuclideanSpace')
+
 def Minkowski(positive_spacelike=True, names=None):
     """
     Generate a Minkowski space of dimension 4.
@@ -124,7 +133,7 @@ def Sphere(dim=None, radius=1, names=None, stereo2d=False, stereo_lim=None):
     from sage.symbolic.constants import pi
     from sage.misc.misc_c import prod
     from sage.manifolds.manifold import Manifold
-    from sage.manifolds.differentiable.euclidean import EuclideanSpace
+    from sage.manifolds.differentiable.examples.euclidean import EuclideanSpace
 
     if dim is None:
         if names is None:
@@ -365,7 +374,7 @@ def Torus(R=2, r=1, names=None):
     """
     from sage.functions.trig import cos, sin
     from sage.manifolds.manifold import Manifold
-    from sage.manifolds.differentiable.euclidean import EuclideanSpace
+    from sage.manifolds.differentiable.examples.euclidean import EuclideanSpace
     E = EuclideanSpace(3, symbols='X Y Z')
     M = Manifold(2, 'T', ambient=E, structure="Riemannian")
     if names is None:

src/sage/manifolds/differentiable/curve.py

@@ -86,7 +86,7 @@ class DifferentiableCurve(DiffMap):
     Instead of declaring the parameter `t`  as a symbolic variable by means
     of ``var('t')``, it is equivalent to get it as the canonical coordinate
     of the real number line (see
-    :class:`~sage.manifolds.differentiable.real_line.RealLine`)::
+    :class:`~sage.manifolds.differentiable.examples.real_line.RealLine`)::
 
         sage: R.<t> = RealLine()
         sage: c = M.curve({X: [sin(t), sin(2*t)/2]}, (t, 0, 2*pi), name='c') ; c

src/sage/manifolds/differentiable/examples/__init__.py

@@ -447,11 +447,11 @@ class EuclideanSpace(PseudoRiemannianManifold):
 
       - ``'Cartesian'`` (canonical coordinates on `\RR^n`)
       - ``'polar'`` for ``n=2`` only (see
-        :meth:`~sage.manifolds.differentiable.euclidean.EuclideanPlane.polar_coordinates`)
+        :meth:`~sage.manifolds.differentiable.examples.euclidean.EuclideanPlane.polar_coordinates`)
       - ``'spherical'`` for ``n=3`` only (see
-        :meth:`~sage.manifolds.differentiable.euclidean.Euclidean3dimSpace.spherical_coordinates`)
+        :meth:`~sage.manifolds.differentiable.examples.euclidean.Euclidean3dimSpace.spherical_coordinates`)
       - ``'cylindrical'`` for ``n=3`` only (see
-        :meth:`~sage.manifolds.differentiable.euclidean.Euclidean3dimSpace.cylindrical_coordinates`)
+        :meth:`~sage.manifolds.differentiable.examples.euclidean.Euclidean3dimSpace.cylindrical_coordinates`)
 
     - ``symbols`` -- (default: ``None``) string defining the coordinate
       text symbols and LaTeX symbols, with the same conventions as the
@@ -656,12 +656,12 @@ def __classcall_private__(cls, n=None, name=None, latex_name=None,
             sage: E2.<x,y> = EuclideanSpace(); E2
             Euclidean plane E^2
             sage: type(E2)
-            <class 'sage.manifolds.differentiable.euclidean.EuclideanPlane_with_category'>
+            <class 'sage.manifolds.differentiable.examples.euclidean.EuclideanPlane_with_category'>
 
             sage: E3.<r,t,p> = EuclideanSpace(coordinates='spherical'); E3
             Euclidean space E^3
             sage: type(E3)
-            <class 'sage.manifolds.differentiable.euclidean.Euclidean3dimSpace_with_category'>
+            <class 'sage.manifolds.differentiable.examples.euclidean.Euclidean3dimSpace_with_category'>
             sage: E3.default_frame()._latex_indices
             (r, {\theta}, {\phi})
         """
@@ -1589,7 +1589,7 @@ class Euclidean3dimSpace(EuclideanSpace):
     a dynamically generated subclass of it via SageMath's category framework)::
 
         sage: type(E)
-        <class 'sage.manifolds.differentiable.euclidean.Euclidean3dimSpace_with_category'>
+        <class 'sage.manifolds.differentiable.examples.euclidean.Euclidean3dimSpace_with_category'>
 
     ``E`` is both a real smooth manifold of dimension `3` and a complete metric
     space::

…ge/manifolds/differentiable/euclidean.py …lds/differentiable/examples/euclidean.pysrc/sage/manifolds/differentiable/euclidean.py renamed to src/sage/manifolds/differentiable/examples/euclidean.py src/sage/manifolds/differentiable/euclidean.py renamed to src/sage/manifolds/differentiable/examples/euclidean.py

@@ -636,7 +636,7 @@ def open_interval(self, lower, upper, name=None, latex_name=None):
 
         OUTPUT:
 
-        - :class:`~sage.manifolds.differentiable.real_line.OpenInterval`
+        - :class:`~sage.manifolds.differentiable.examples.real_line.OpenInterval`
           representing the open interval (``lower``, ``upper``)
 
         EXAMPLES:
@@ -738,7 +738,7 @@ class RealLine(OpenInterval):
         False
 
     The canonical coordinate is returned by the method
-    :meth:`~sage.manifolds.differentiable.real_line.OpenInterval.canonical_coordinate`::
+    :meth:`~sage.manifolds.differentiable.examples.real_line.OpenInterval.canonical_coordinate`::
 
         sage: R.canonical_coordinate()
         t
@@ -812,15 +812,15 @@ class RealLine(OpenInterval):
 
     The real line is considered as the open interval `(-\infty, +\infty)`::
 
-        sage: isinstance(R, sage.manifolds.differentiable.real_line.OpenInterval)
+        sage: isinstance(R, sage.manifolds.differentiable.examples.real_line.OpenInterval)
         True
         sage: R.lower_bound()
         -Infinity
         sage: R.upper_bound()
         +Infinity
 
     A real interval can be created from ``R`` means of the method
-    :meth:`~sage.manifolds.differentiable.real_line.OpenInterval.open_interval`::
+    :meth:`~sage.manifolds.differentiable.examples.real_line.OpenInterval.open_interval`::
 
         sage: I = R.open_interval(0, 1); I
         Real interval (0, 1)

…ge/manifolds/differentiable/real_line.py …lds/differentiable/examples/real_line.pysrc/sage/manifolds/differentiable/real_line.py renamed to src/sage/manifolds/differentiable/examples/real_line.py src/sage/manifolds/differentiable/real_line.py renamed to src/sage/manifolds/differentiable/examples/real_line.py

@@ -3439,7 +3439,7 @@ def curve(self, coord_expression, param, chart=None,
             for more examples, including plots.
 
         """
-        from sage.manifolds.differentiable.real_line import RealLine
+        from sage.manifolds.differentiable.examples.real_line import RealLine
         if not isinstance(param, (tuple, list)):
             param = (param, minus_infinity, infinity)
         elif len(param) != 3:
@@ -3560,7 +3560,7 @@ def integrated_curve(self, equations_rhs, velocities, curve_param,
 
         """
 
-        from sage.manifolds.differentiable.real_line import RealLine
+        from sage.manifolds.differentiable.examples.real_line import RealLine
         from sage.manifolds.differentiable.manifold_homset import IntegratedCurveSet
 
         if len(curve_param) != 3:
@@ -3695,7 +3695,7 @@ def integrated_autoparallel_curve(self, affine_connection,
 
         """
 
-        from sage.manifolds.differentiable.real_line import RealLine
+        from sage.manifolds.differentiable.examples.real_line import RealLine
         from sage.manifolds.differentiable.manifold_homset import IntegratedAutoparallelCurveSet
 
         if len(curve_param) != 3:
@@ -3816,7 +3816,7 @@ def integrated_geodesic(self, metric, curve_param,
             [-1.0907409234671228, 0.6205670379855032]
 
         """
-        from sage.manifolds.differentiable.real_line import RealLine
+        from sage.manifolds.differentiable.examples.real_line import RealLine
         from sage.manifolds.differentiable.manifold_homset import IntegratedGeodesicSet
 
         if len(curve_param) != 3: