default frame added to vector bundles + doctree modified

Author: Michael Jung

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

@@ -30,4 +30,4 @@ Differentiable Manifolds
 
    sage/manifolds/differentiable/differentiable_submanifold
 
-   sage/manifolds/differentiable/vector_bundle
+   diff_vector_bundle

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

@@ -0,0 +1,7 @@
+Differentiable Vector Bundles
+=============================
+
+.. toctree::
+   :maxdepth: 2
+
+   sage/manifolds/differentiable/vector_bundle

src/sage/manifolds/differentiable/vector_bundle.py

@@ -351,9 +351,7 @@ def _init_derived(self):
             sage: TM._init_derived()
 
         """
-        ###
-        # Nothing to do here:
-        pass
+        self._def_frame = None
 
     def _repr_(self):
         r"""
@@ -1353,3 +1351,87 @@ def destination_map(self):
 
         """
         return self._dest_map
+
+    def default_frame(self):
+        r"""
+        Return the default vector frame defined on ``self``.
+
+        By *vector frame*, it is meant a field on the manifold that provides,
+        at each point `p`, a vector basis of the pulled back tangent space at
+        `p`.
+
+        If the destination map is the identity map, the default frame is the
+        the first one defined on the manifold, usually the coordinate frame,
+        unless it is changed via :meth:`set_default_frame`.
+
+        If the destination map is non-trivial, the default frame usually must be
+        set via :meth:`set_default_frame`.
+
+        OUTPUT:
+
+        - a :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame`
+          representing the default vector frame
+
+        EXAMPLES:
+
+        The default vector frame is often the coordinate frame associated
+        with the first chart defined on the manifold::
+
+            sage: M = Manifold(2, 'M')
+            sage: c_xy.<x,y> = M.chart()
+            sage: TM = M.tangent_bundle()
+            sage: TM.default_frame()
+            Coordinate frame (M, (d/dx,d/dy))
+
+        """
+        def_bframe = self._base_space.default_frame()
+        if self._def_frame is None and def_bframe is not None:
+            if def_bframe._dest_map == self._dest_map:
+                self._def_frame = def_bframe
+        return self._def_frame
+
+    def set_default_frame(self, frame):
+        r"""
+        Changing the default vector frame on ``self``.
+
+        .. NOTE::
+
+            If the destination map is the identity, the default frame of the
+            base manifold gets changed here as well.
+
+        INPUT:
+
+        - ``frame`` --
+          :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame`
+          a vector frame defined on the base manifold
+
+        EXAMPLES:
+
+        Changing the default frame on the tangent bundle of a 2-dimensional
+        manifold::
+
+            sage: M = Manifold(2, 'M')
+            sage: c_xy.<x,y> = M.chart()
+            sage: TM = M.tangent_bundle()
+            sage: e = TM.vector_frame('e')
+            sage: TM.default_frame()
+            Coordinate frame (M, (d/dx,d/dy))
+            sage: TM.set_default_frame(e)
+            sage: TM.default_frame()
+            Vector frame (M, (e_0,e_1))
+            sage: M.default_frame()
+            Vector frame (M, (e_0,e_1))
+
+        """
+        from sage.manifolds.differentiable.vectorframe import VectorFrame
+        if not isinstance(frame, VectorFrame):
+            raise TypeError("{} is not a vector frame".format(frame))
+        if (not frame._domain.is_subset(self._base_space) or
+                frame._dest_map != self._dest_map):
+            raise ValueError("the frame must be defined on " +
+                             "the {}".format(self))
+        if self._dest_map.is_identity():
+            self._base_space.set_default_frame(frame)
+        else:
+            frame._fmodule.set_default_basis(frame)
+        self._def_frame = frame

src/sage/manifolds/local_frame.py

@@ -634,6 +634,8 @@ def __init__(self, section_module, symbol, latex_symbol=None, indices=None,
                                  indices=indices, latex_indices=latex_indices,
                                  symbol_dual=symbol_dual,
                                  latex_symbol_dual=latex_symbol_dual)
+        if self._vbundle._def_frame is None:
+            self._vbundle._def_frame = self
         # The frame is added to the domain's modules of frames, as well as to
         # all the superdomain's modules of frames; moreover the first defined
         # frame is considered as the default one

src/sage/manifolds/vector_bundle.py

@@ -273,6 +273,7 @@ def _init_derived(self):
         self._coframes = [] # list of local coframes for self
         self._trivial_parts = set() # subsets of base space on which self is
                                     # trivial
+        self._def_frame = None
 
     def base_space(self):
         r"""
@@ -1032,3 +1033,54 @@ def coframes(self):
 
         """
         return list(self._coframes)
+
+    def default_frame(self):
+        r"""
+        Return the default frame of on ``self``.
+
+        OUTPUT:
+
+        - a local frame as an instance of
+          :class:`~sage.manifolds.local_frame.LocalFrame`
+
+        EXAMPLES::
+
+            sage: M = Manifold(3, 'M', structure='top')
+            sage: E = M.vector_bundle(2, 'E')
+            sage: e = E.local_frame('e')
+            sage: E.default_frame()
+            Local frame (E|_M, (e_0,e_1))
+
+        """
+        return self._def_frame
+
+    def set_default_frame(self, frame):
+        r"""
+        Set the default frame of ``self``.
+
+        INPUT:
+
+        - ``frame`` -- a local frame defined on ``self`` as an instance of
+          :class:`~sage.manifolds.local_frame.LocalFrame`
+
+        EXAMPLES::
+
+            sage: M = Manifold(3, 'M', structure='top')
+            sage: E = M.vector_bundle(2, 'E')
+            sage: e = E.local_frame('e')
+            sage: E.default_frame()
+            Local frame (E|_M, (e_0,e_1))
+            sage: f = E.local_frame('f')
+            sage: E.set_default_frame(f)
+            sage: E.default_frame()
+            Local frame (E|_M, (f_0,f_1))
+
+        """
+        from sage.manifolds.local_frame import LocalFrame
+        if not isinstance(frame, LocalFrame):
+            raise TypeError("{} is not a local frame".format(frame))
+        if not frame._domain.is_subset(self._base_space):
+            raise ValueError("the frame must be defined on " +
+                             "the {}".format(self))
+        frame._fmodule.set_default_basis(frame)
+        self._def_frame = frame