src/sage/manifolds/differentiable/diff_form_module.py (VectorFieldDua…

…lFreeModule): New

src/sage/manifolds/differentiable/diff_form_module.py

@@ -905,3 +905,175 @@ def _repr_(self):
             description += "along the {} mapped into the {}".format(
                                             self._domain, self._ambient_domain)
         return description
+
+
+class VectorFieldDualFreeModule(DiffFormFreeModule):
+    r"""
+    Free module of differential 1-forms along a differentiable manifold `U`
+    with values on a parallelizable manifold `M`.
+
+    Given a differentiable manifold `U` and a differentiable map
+    `\Phi:\; U \rightarrow M` to a parallelizable manifold `M` of dimension
+    `n`, the set `\Omega^1(U, \Phi)` of 1-forms along `U` with values on `M`
+    is a free module of rank `n` over `C^k(U)`, the commutative
+    algebra of differentiable scalar fields on `U` (see
+    :class:`~sage.manifolds.differentiable.scalarfield_algebra.DiffScalarFieldAlgebra`).
+    The standard case of 1-forms *on* a differentiable manifold `M`
+    corresponds to `U = M` and `\Phi = \mathrm{Id}_M`. Other common cases are
+    `\Phi` being an immersion and `\Phi` being a curve in `M` (`U` is then an
+    open interval of `\RR`).
+
+    .. NOTE::
+
+        This class implements `\Omega^1(U, \Phi)` in the case where `M` is
+        parallelizable; `\Omega^1(U, \Phi)` is then a *free* module. If `M`
+        is not parallelizable, the class :class:`DiffFormModule` must be used
+        instead.
+
+    INPUT:
+
+    - ``vector_field_module`` -- free module `\mathfrak{X}(U,\Phi)` of vector
+      fields along `U` associated with the map `\Phi: U \rightarrow V`
+
+    EXAMPLES:
+
+    Free module of 1-forms on a parallelizable 3-dimensional manifold::
+
+        sage: M = Manifold(3, 'M')
+        sage: X.<x,y,z> = M.chart()
+        sage: XM = M.vector_field_module() ; XM
+        Free module X(M) of vector fields on the 3-dimensional differentiable
+         manifold M
+        sage: A = M.diff_form_module(1) ; A
+        Free module Omega^1(M) of 1-forms on the 3-dimensional differentiable manifold M
+        sage: latex(A)
+        \Omega^{1}\left(M\right)
+
+    ``A`` is nothing but the dual of ``XM`` (the free module of vector fields on `M`)
+    and thus also equal to the 1st exterior
+    power of the dual, i.e. we have `\Omega^{1}(M) = \Lambda^1(\mathfrak{X}(M)^*)
+    = \mathfrak{X}(M)^*` (See
+    :class:`~sage.tensor.modules.ext_pow_free_module.ExtPowerDualFreeModule`)::
+
+        sage: A is XM.dual_exterior_power(1)
+        True
+
+    `\Omega^{1}(M)` is a module over the algebra `C^k(M)` of (differentiable)
+    scalar fields on `M`::
+
+        sage: A.category()
+        Category of finite dimensional modules over Algebra of differentiable
+         scalar fields on the 3-dimensional differentiable manifold M
+        sage: CM = M.scalar_field_algebra() ; CM
+        Algebra of differentiable scalar fields on the 3-dimensional
+         differentiable manifold M
+        sage: A in Modules(CM)
+        True
+        sage: A.base_ring()
+        Algebra of differentiable scalar fields on
+         the 3-dimensional differentiable manifold M
+        sage: A.base_module()
+        Free module X(M) of vector fields on
+         the 3-dimensional differentiable manifold M
+        sage: A.base_module() is XM
+        True
+        sage: A.rank()
+        3
+
+    Elements can be constructed from `A`. In particular, ``0`` yields
+    the zero element of `A`::
+
+        sage: A(0)
+        1-form zero on the 3-dimensional differentiable manifold M
+        sage: A(0) is A.zero()
+        True
+
+    while non-zero elements are constructed by providing their components
+    in a given vector frame::
+
+        sage: comp = [3*x,-z,4]
+        sage: a = A(comp, frame=X.frame(), name='a') ; a
+        1-form a on the 3-dimensional differentiable manifold M
+        sage: a.display()
+        a = 3*x dx - z dy + 4 dz
+
+    An alternative is to construct the 1-form from an empty list of
+    components and to set the nonzero nonredundant components afterwards::
+
+        sage: a = A([], name='a')
+        sage: a[0] = 3*x  # component in the manifold's default frame
+        sage: a[1] = -z
+        sage: a[2] = 4
+        sage: a.display()
+        a = 3*x dx - z dy + 4 dz
+
+    Since any tensor field of type `(0,1)` is a 1-form, there is a coercion
+    map from the set `T^{(0,1)}(M)` of such tensors to `\Omega^1(M)`::
+
+        sage: T01 = M.tensor_field_module((0,1)) ; T01
+        Free module T^(0,1)(M) of type-(0,1) tensors fields on the
+         3-dimensional differentiable manifold M
+        sage: A.has_coerce_map_from(T01)
+        True
+
+    There is also a coercion map in the reverse direction::
+
+        sage: T01.has_coerce_map_from(A)
+        True
+
+    The coercion map `T^{(0,1)}(M) \rightarrow \Omega^1(M)` in action::
+
+        sage: b = T01([-x,2,3*y], name='b'); b
+        Tensor field b of type (0,1) on the 3-dimensional differentiable
+         manifold M
+        sage: b.display()
+        b = -x dx + 2 dy + 3*y dz
+        sage: lb = A(b) ; lb
+        1-form b on the 3-dimensional differentiable manifold M
+        sage: lb.display()
+        b = -x dx + 2 dy + 3*y dz
+
+    The coercion map `\Omega^1(M) \rightarrow T^{(0,1)}(M)` in action::
+
+        sage: tlb = T01(lb); tlb
+        Tensor field b of type (0,1) on
+         the 3-dimensional differentiable manifold M
+        sage: tlb == b
+        True
+    """
+
+    def __init__(self, vector_field_module):
+        r"""
+        Construct a free module of differential 1-forms.
+
+        TESTS::
+
+            sage: M = Manifold(3, 'M')
+            sage: X.<x,y,z> = M.chart()
+            sage: from sage.manifolds.differentiable.diff_form_module import DiffFormFreeModule
+            sage: A = DiffFormFreeModule(M.vector_field_module(), 1) ; A
+            Free module Omega^1(M) of 1-forms on the 3-dimensional differentiable manifold M
+            sage: TestSuite(A).run()
+            Traceback (most recent call last):
+            ...
+            The following tests failed: _test_zero
+
+        """
+        DiffFormFreeModule.__init__(self, vector_field_module, 1)
+
+    def tensor_type(self):
+        r"""
+        Return the tensor type of ``self``.
+
+        EXAMPLES::
+
+            sage: M = Manifold(3, 'M')
+            sage: X.<x,y,z> = M.chart()
+            sage: from sage.manifolds.differentiable.diff_form_module import DiffFormFreeModule
+            sage: A = M.vector_field_module().dual(); A
+            Free module Omega^1(M) of 1-forms on the 3-dimensional differentiable manifold M
+            sage: A.tensor_type()
+            (0, 1)
+
+        """
+        return (0, 1)

src/sage/manifolds/differentiable/vectorfield_module.py

@@ -1893,8 +1893,7 @@ def dual_exterior_power(self, p):
             Free module Omega^2(M) of 2-forms on the 2-dimensional
              differentiable manifold M
             sage: XM.dual_exterior_power(1)
-            Free module Omega^1(M) of 1-forms on the 2-dimensional
-             differentiable manifold M
+            Free module Omega^1(M) of 1-forms on the 2-dimensional differentiable manifold M
             sage: XM.dual_exterior_power(1) is XM.dual()
             True
             sage: XM.dual_exterior_power(0)
@@ -1914,6 +1913,10 @@ def dual_exterior_power(self, p):
         except KeyError:
             if p == 0:
                 L = self._ring
+            elif p == 1:
+                from sage.manifolds.differentiable.diff_form_module import \
+                                                      VectorFieldDualFreeModule
+                L = VectorFieldDualFreeModule(self)
             else:
                 from sage.manifolds.differentiable.diff_form_module import \
                                                       DiffFormFreeModule