Trac #27784: Merge trac #28716 into trac #27784

Author: Michael Jung

src/sage/manifolds/differentiable/manifold.py

@@ -2786,28 +2786,33 @@ def set_change_of_frame(self, frame1, frame2, change_of_frame,
                 for sdom in self._supersets:
                     sdom._frame_changes[(frame2, frame1)] = change_of_frame.inverse()
 
-    def vector_frame(self, symbol=None, latex_symbol=None, dest_map=None,
-                     from_frame=None, indices=None, latex_indices=None,
-                     symbol_dual=None, latex_symbol_dual=None):
+    def vector_frame(self, *args, **kwargs):
         r"""
         Define a vector frame on ``self``.
 
         A *vector frame* is a field on the manifold that provides, at each
         point `p` of the manifold, a vector basis of the tangent space at `p`
         (or at `\Phi(p)` when ``dest_map`` is not ``None``, see below).
 
+        The vector frame can be defined from a set of `n` linearly independent
+        vector fields, `n` being the dimension of ``self``.
+
         .. SEEALSO::
 
             :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame`
             for complete documentation.
 
         INPUT:
 
-        - ``symbol`` -- (default: ``None``) either a string, to be used as a
+        - ``symbol`` -- either a string, to be used as a
           common base for the symbols of the vector fields constituting the
           vector frame, or a list/tuple of strings, representing the individual
-          symbols of the vector fields; can be ``None`` only if ``from_frame``
+          symbols of the vector fields; can be omitted only if ``from_frame``
           is not ``None`` (see below)
+        - ``vector_fields`` -- tuple or list of `n` linearly independent vector
+          fields on the manifold ``self`` (`n` being the dimension of ``self``)
+          defining the vector frame; can be omitted if the vector frame is
+          created from scratch or if ``from_frame`` is not ``None``
         - ``latex_symbol`` -- (default: ``None``) either a string, to be used
           as a common base for the LaTeX symbols of the vector fields
           constituting the vector frame, or a list/tuple of strings,
@@ -2818,8 +2823,8 @@ def vector_frame(self, symbol=None, latex_symbol=None, dest_map=None,
           destination map `\Phi:\ U \rightarrow M`, where `U` is ``self`` and
           `M` is a differentiable manifold; for each `p\in U`, the vector
           frame evaluated at `p` is a basis of the tangent space
-          `T_{\Phi(p)}M`; if ``dest_map`` is ``None``, the identity is assumed
-          (case of a vector frame *on* `U`)
+          `T_{\Phi(p)}M`; if ``dest_map`` is ``None``, the identity map is
+          assumed (case of a vector frame *on* `U`)
         - ``from_frame`` -- (default: ``None``) vector frame `\tilde{e}`
           on the codomain `M` of the destination map `\Phi`; the returned
           frame `e` is then such that for all `p \in U`,
@@ -2845,14 +2850,72 @@ def vector_frame(self, symbol=None, latex_symbol=None, dest_map=None,
 
         EXAMPLES:
 
-        Setting a vector frame on a 3-dimensional manifold::
+        Defining a vector frame from two linearly independent vector
+        fields on a 2-dimensional manifold::
 
-            sage: M = Manifold(3, 'M')
-            sage: X.<x,y,z> = M.chart()
-            sage: e = M.vector_frame('e'); e
-            Vector frame (M, (e_0,e_1,e_2))
-            sage: e[0]
-            Vector field e_0 on the 3-dimensional differentiable manifold M
+            sage: M = Manifold(2, 'M')
+            sage: X.<x,y> = M.chart()
+            sage: e0 = M.vector_field(1+x^2, 1+y^2)
+            sage: e1 = M.vector_field(2, -x*y)
+            sage: e = M.vector_frame('e', (e0, e1)); e
+            Vector frame (M, (e_0,e_1))
+            sage: e[0].display()
+            e_0 = (x^2 + 1) d/dx + (y^2 + 1) d/dy
+            sage: e[1].display()
+            e_1 = 2 d/dx - x*y d/dy
+            sage: (e[0], e[1]) == (e0, e1)
+            True
+
+        If the vector fields are not linearly independent, an error is
+        raised::
+
+            sage: z = M.vector_frame('z', (e0, -e0))
+            Traceback (most recent call last):
+            ...
+            ValueError: the provided vector fields are not linearly
+             independent
+
+        Another example, involving a pair vector fields along a curve::
+
+            sage: R.<t> = RealLine()
+            sage: c = M.curve([sin(t), sin(2*t)/2], (t, 0, 2*pi), name='c')
+            sage: I = c.domain(); I
+            Real interval (0, 2*pi)
+            sage: v = c.tangent_vector_field()
+            sage: v.display()
+            c' = cos(t) d/dx + (2*cos(t)^2 - 1) d/dy
+            sage: w = I.vector_field(1-2*cos(t)^2, cos(t), dest_map=c)
+            sage: u = I.vector_frame('u', (v, w))
+            sage: u[0].display()
+            u_0 = cos(t) d/dx + (2*cos(t)^2 - 1) d/dy
+            sage: u[1].display()
+            u_1 = (-2*cos(t)^2 + 1) d/dx + cos(t) d/dy
+            sage: (u[0], u[1]) == (v, w)
+            True
+
+        It is also possible to create a vector frame from scratch, without
+        connecting it to previously defined vector frames or vector fields
+        (this can still be performed later via the method
+        :meth:`~sage.manifolds.differentiable.manifold.DifferentiableManifold.set_change_of_frame`)::
+
+            sage: f = M.vector_frame('f'); f
+            Vector frame (M, (f_0,f_1))
+            sage: f[0]
+            Vector field f_0 on the 2-dimensional differentiable manifold M
+
+        Thanks to the keywords ``dest_map`` and ``from_frame``, one can also
+        define a vector frame from one prexisting on another manifold, via a
+        differentiable map (here provided by the curve ``c``)::
+
+            sage: fc = I.vector_frame(dest_map=c, from_frame=f); fc
+            Vector frame ((0, 2*pi), (f_0,f_1)) with values on the
+             2-dimensional differentiable manifold M
+            sage: fc[0]
+            Vector field f_0 along the Real interval (0, 2*pi) with values on
+             the 2-dimensional differentiable manifold M
+
+        Note that the symbol for ``fc``, namely `f`, is inherited from ``f``,
+        the original vector frame.
 
         .. SEEALSO::
 
@@ -2862,12 +2925,53 @@ def vector_frame(self, symbol=None, latex_symbol=None, dest_map=None,
 
         """
         from sage.manifolds.differentiable.vectorframe import VectorFrame
-        return VectorFrame(self.vector_field_module(dest_map=dest_map,
+        # Input processing
+        symbol = None
+        vector_fields = None
+        n_args = len(args)
+        if n_args >= 1:
+            symbol = args[0]
+        if n_args == 2:
+            vector_fields = args[1]
+        elif n_args > 2:
+            raise TypeError("vector_frame() takes at most two positional "
+                            "arguments")
+        latex_symbol = kwargs.pop('latex_symbol', None)
+        dest_map = kwargs.pop('dest_map', None)
+        from_frame = kwargs.pop('from_frame', None)
+        indices = kwargs.pop('indices', None)
+        latex_indices = kwargs.pop('latex_indices', None)
+        symbol_dual = kwargs.pop('symbol_dual', None)
+        latex_symbol_dual = kwargs.pop('latex_symbol_dual', None)
+        #
+        if vector_fields:
+            dest_map0 = vector_fields[0].parent().destination_map()
+            if dest_map and dest_map is not dest_map0:
+                raise ValueError("incompatible values of destination maps")
+            dest_map = dest_map0
+        resu = VectorFrame(self.vector_field_module(dest_map=dest_map,
                                                     force_free=True),
                            symbol=symbol, latex_symbol=latex_symbol,
                            from_frame=from_frame, indices=indices,
                            latex_indices=latex_indices, symbol_dual=symbol_dual,
                            latex_symbol_dual=latex_symbol_dual)
+        if vector_fields:
+            linked = False
+            try:
+                resu._init_from_family(vector_fields)
+            except ArithmeticError as err:
+                linked = str(err) in ["non-invertible matrix",
+                                      "input matrix must be nonsingular"]
+            if linked:
+                raise ValueError("the provided vector fields are not "
+                                 "linearly independent")
+            # Adding the newly generated changes of frame to the
+            # dictionary _frame_changes of self and its supersets:
+            for frame_pair, chge in resu._fmodule._basis_changes.items():
+                if resu in frame_pair:
+                    for sdom in self._supersets:
+                        sdom._frame_changes[frame_pair] = chge
+        return resu
 
     def _set_covering_frame(self, frame):
         r"""

src/sage/manifolds/differentiable/vector_bundle.py

@@ -1309,9 +1309,7 @@ def is_manifestly_trivial(self):
                     return True
             return False
 
-    def local_frame(self, symbol=None, latex_symbol=None, from_frame=None,
-                    indices=None, latex_indices=None, symbol_dual=None,
-                    latex_symbol_dual=None, domain=None):
+    def local_frame(self, *args, **kwargs):
         r"""
         Define a vector frame on ``domain``, possibly with values in the
         tangent bundle of the ambient domain.
@@ -1354,6 +1352,10 @@ def local_frame(self, symbol=None, latex_symbol=None, from_frame=None,
           vector frame, or a list/tuple of strings, representing the individual
           symbols of the vector fields; can be ``None`` only if ``from_frame``
           is not ``None`` (see below)
+        - ``vector_fields`` -- tuple or list of `n` linearly independent vector
+          fields on ``domain`` (`n` being the dimension of  ``domain``)
+          defining the vector frame; can be omitted if the vector frame is
+          created from scratch or if ``from_frame`` is not ``None``
         - ``latex_symbol`` -- (default: ``None``) either a string, to be used
           as a common base for the LaTeX symbols of the vector fields
           constituting the vector frame, or a list/tuple of strings,
@@ -1414,16 +1416,17 @@ def local_frame(self, symbol=None, latex_symbol=None, from_frame=None,
             :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame`.
 
         """
+        domain = kwargs.pop('domain', None)
         if domain is None:
             domain = self._base_space
-        vmodule = domain.vector_field_module(
-                                       dest_map=self._dest_map.restrict(domain),
-                                       force_free=True)
-        return vmodule.basis(symbol=symbol, latex_symbol=latex_symbol,
-                             from_frame=from_frame,
-                             indices=indices, latex_indices=latex_indices,
-                             symbol_dual=symbol_dual,
-                             latex_symbol_dual=latex_symbol_dual)
+        dest_map = self._dest_map.restrict(domain)
+        if not args and not kwargs:
+            # if no argument is provided, the default basis of the
+            # base vector field module is returned:
+            return domain.vector_field_module(dest_map=dest_map,
+                                              force_free=True).basis()
+        kwargs['dest_map'] = dest_map
+        return domain.vector_frame(*args, **kwargs)
 
     vector_frame = local_frame
 
@@ -1568,4 +1571,4 @@ def set_default_frame(self, frame):
             self._base_space.set_default_frame(frame)
         else:
             frame._fmodule.set_default_basis(frame)
-        self._def_frame = frame
+        self._def_frame = frame

src/sage/manifolds/differentiable/vectorframe.py

@@ -34,18 +34,29 @@
 
 EXAMPLES:
 
-Defining a vector frame on a 3-dimensional manifold::
+Introducing a chart on a manifold automatically endows it with a vector frame:
+the coordinate frame associated to the chart::
 
     sage: M = Manifold(3, 'M')
     sage: X.<x,y,z> = M.chart()
-    sage: e = M.vector_frame('e') ; e
+    sage: M.frames()
+    [Coordinate frame (M, (d/dx,d/dy,d/dz))]
+    sage: M.frames()[0] is X.frame()
+    True
+
+A new vector frame can be defined from a family of 3 linearly independent
+vector fields::
+
+    sage: e1 = M.vector_field(1, x, y)
+    sage: e2 = M.vector_field(z, -2, x*y)
+    sage: e3 = M.vector_field(1, 1, 0)
+    sage: e = M.vector_frame('e', (e1, e2, e3)); e
     Vector frame (M, (e_0,e_1,e_2))
     sage: latex(e)
     \left(M, \left(e_{0},e_{1},e_{2}\right)\right)
 
-The first frame defined on a manifold is its default frame; in the present
-case it is the coordinate frame defined when introducing the chart
-``X``::
+The first frame defined on a manifold is its *default frame*; in the present
+case it is the coordinate frame associated to the chart ``X``::
 
     sage: M.default_frame()
     Coordinate frame (M, (d/dx,d/dy,d/dz))
@@ -70,6 +81,13 @@
 
     sage: e[0]
     Vector field e_0 on the 3-dimensional differentiable manifold M
+    sage: e[0].display(X.frame())
+    e_0 = d/dx + x d/dy + y d/dz
+    sage: X.frame()[1]
+    Vector field d/dy on the 3-dimensional differentiable manifold M
+    sage: X.frame()[1].display(e)
+    d/dy = x/(x^2 - x + z + 2) e_0 - 1/(x^2 - x + z + 2) e_1
+     - (x - z)/(x^2 - x + z + 2) e_2
 
 The slice operator ``:`` can be used to access to more than one element::
 
@@ -81,6 +99,18 @@
      Vector field e_1 on the 3-dimensional differentiable manifold M,
      Vector field e_2 on the 3-dimensional differentiable manifold M)
 
+Vector frames can be constructed from scratch, without any connection to
+previously defined frames or vector fields (the connection can be performed
+later via the method
+:meth:`~sage.manifolds.differentiable.manifold.DifferentiableManifold.set_change_of_frame`)::
+
+    sage: f = M.vector_frame('f'); f
+    Vector frame (M, (f_0,f_1,f_2))
+    sage: M.frames()
+    [Coordinate frame (M, (d/dx,d/dy,d/dz)),
+     Vector frame (M, (e_0,e_1,e_2)),
+     Vector frame (M, (f_0,f_1,f_2))]
+
 The index range depends on the starting index defined on the manifold::
 
     sage: M = Manifold(3, 'M', start_index=1)
@@ -152,14 +182,12 @@
 
 The orthonormal frame constructed from the coordinate frame::
 
-    sage: change_frame = M.automorphism_field()
-    sage: change_frame[:] = [[1,0], [0, 1/sin(th)]]
-    sage: e = b.new_frame(change_frame, 'e') ; e
+    sage: e = M.vector_frame('e', (b[1], b[2]/sin(th))); e
     Vector frame (S^2, (e_1,e_2))
-    sage: e[1][:]
-    [1, 0]
-    sage: e[2][:]
-    [0, 1/sin(th)]
+    sage: e[1].display()
+    e_1 = d/dth
+    sage: e[2].display()
+    e_2 = 1/sin(th) d/dph
 
 The change-of-frame automorphisms and their matrices::