Trac #30229: Submodules of TensorFreeModule defined by the symmetries of a Components object

We generalize `FiniteRankFreeModule.tensor_module` by giving it optional
arguments `sym`, `antisym`; if given, a submodule of the tensor module
spanned by the tensors with these prescribed symmetries is created.

The new methods `symmetric_power` and `dual_symmetric_power` provide two
important special cases.

The implementation makes the standard bases of tensor modules (and of
their new submodules) explicit objects.  The `basis` method now works
for tensor modules, not just the base module, and returns an instance of
the new class `TensorFreeSubmoduleBasis_sym`, which represents the
standard basis corresponding to an instance of the `Components` class
(or one of its subclasses).

Follow-ups:
- #34427 `TensorFreeModule.isomorphism_with_fixed_basis`
- #30242 Make `ExtPowerFreeModule` a quotient of `TensorFreeModule`
- #30307 Refactor `Component`s into parent (a `ModuleWithBasis`) &
element

URL: https://trac.sagemath.org/30229
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe
Reviewer(s): Eric Gourgoulhon

Author: Release Manager

src/doc/en/reference/tensor_free_modules/tensors.rst

@@ -6,6 +6,10 @@ Tensors
 
    sage/tensor/modules/tensor_free_module
 
+   sage/tensor/modules/tensor_free_submodule
+
    sage/tensor/modules/free_module_tensor
 
    sage/tensor/modules/tensor_with_indices
+
+   sage/tensor/modules/tensor_free_submodule_basis

src/sage/tensor/modules/comp.py

@@ -525,15 +525,48 @@ def _repr_(self):
             sage: c._repr_()
             '2-indices components w.r.t. [1, 2, 3]'
 
+            sage: from sage.tensor.modules.comp import CompWithSym
+            sage: CompWithSym(ZZ, [1,2,3], 4, sym=(0,1))
+            4-indices components w.r.t. [1, 2, 3],
+             with symmetry on the index positions (0, 1)
+            sage: CompWithSym(ZZ, [1,2,3], 4, sym=(0,1), antisym=(2,3))
+            4-indices components w.r.t. [1, 2, 3],
+             with symmetry on the index positions (0, 1),
+             with antisymmetry on the index positions (2, 3)
+
+            sage: from sage.tensor.modules.comp import CompFullySym
+            sage: CompFullySym(ZZ, (1,2,3), 4)
+            Fully symmetric 4-indices components w.r.t. (1, 2, 3)
+
+            sage: from sage.tensor.modules.comp import CompFullyAntiSym
+            sage: CompFullyAntiSym(ZZ, (1,2,3), 4)
+            Fully antisymmetric 4-indices components w.r.t. (1, 2, 3)
         """
-        description = str(self._nid)
+        prefix, suffix = self._repr_symmetry()
+        description = prefix
+        description += str(self._nid)
         if self._nid == 1:
             description += "-index"
         else:
             description += "-indices"
         description += " components w.r.t. " + str(self._frame)
+        description += suffix
         return description
 
+    def _repr_symmetry(self):
+        r"""
+        Return a prefix and a suffix string describing the symmetry of ``self``.
+
+        EXAMPLES::
+
+            sage: from sage.tensor.modules.comp import Components
+            sage: c = Components(ZZ, [1,2,3], 2)
+            sage: c._repr_symmetry()
+            ('', '')
+
+        """
+        return "", ""
+
     def _new_instance(self):
         r"""
         Creates a :class:`Components` instance of the same number of indices
@@ -3128,35 +3161,29 @@ def _canonicalize_sym_antisym(nb_indices, sym=None, antisym=None):
                              "index position appears more than once")
         return result_sym, result_antisym
 
-    def _repr_(self):
+    def _repr_symmetry(self):
         r"""
-        Return a string representation of ``self``.
+        Return a prefix and a suffix string describing the symmetry of ``self``.
 
         EXAMPLES::
 
             sage: from sage.tensor.modules.comp import CompWithSym
-            sage: CompWithSym(ZZ, [1,2,3], 4, sym=(0,1))
-            4-indices components w.r.t. [1, 2, 3],
-             with symmetry on the index positions (0, 1)
-            sage: CompWithSym(ZZ, [1,2,3], 4, sym=(0,1), antisym=(2,3))
-            4-indices components w.r.t. [1, 2, 3],
-             with symmetry on the index positions (0, 1),
-             with antisymmetry on the index positions (2, 3)
-
+            sage: cp = CompWithSym(QQ, [1,2,3], 4, sym=(0,1))
+            sage: cp._repr_symmetry()
+            ('', ', with symmetry on the index positions (0, 1)')
+            sage: cp = CompWithSym(QQ, [1,2,3], 4, sym=((0,1),), antisym=((2,3),))
+            sage: cp._repr_symmetry()
+            ('',
+             ', with symmetry on the index positions (0, 1), with antisymmetry on the index positions (2, 3)')
         """
-        description = str(self._nid)
-        if self._nid == 1:
-            description += "-index"
-        else:
-            description += "-indices"
-        description += " components w.r.t. " + str(self._frame)
+        description = ""
         for isym in self._sym:
             description += ", with symmetry on the index positions " + \
                            str(tuple(isym))
         for isym in self._antisym:
             description += ", with antisymmetry on the index positions " + \
                            str(tuple(isym))
-        return description
+        return "", description
 
     def _new_instance(self):
         r"""
@@ -4824,19 +4851,19 @@ def __init__(self, ring, frame, nb_indices, start_index=0,
         CompWithSym.__init__(self, ring, frame, nb_indices, start_index,
                              output_formatter, sym=range(nb_indices))
 
-    def _repr_(self):
+    def _repr_symmetry(self):
         r"""
-        Return a string representation of ``self``.
+        Return a prefix and a suffix string describing the symmetry of ``self``.
 
         EXAMPLES::
 
             sage: from sage.tensor.modules.comp import CompFullySym
-            sage: CompFullySym(ZZ, (1,2,3), 4)
-            Fully symmetric 4-indices components w.r.t. (1, 2, 3)
+            sage: c = CompFullySym(ZZ, (1,2,3), 4)
+            sage: c._repr_symmetry()
+            ('Fully symmetric ', '')
 
         """
-        return "Fully symmetric " + str(self._nid) + "-indices" + \
-              " components w.r.t. " + str(self._frame)
+        return "Fully symmetric ", ""
 
     def _new_instance(self):
         r"""
@@ -5283,19 +5310,19 @@ def __init__(self, ring, frame, nb_indices, start_index=0,
         CompWithSym.__init__(self, ring, frame, nb_indices, start_index,
                              output_formatter, antisym=range(nb_indices))
 
-    def _repr_(self):
+    def _repr_symmetry(self):
         r"""
-        Return a string representation of ``self``.
+        Return a prefix and a suffix string describing the symmetry of ``self``.
 
         EXAMPLES::
 
             sage: from sage.tensor.modules.comp import CompFullyAntiSym
-            sage: CompFullyAntiSym(ZZ, (1,2,3), 4)
-            Fully antisymmetric 4-indices components w.r.t. (1, 2, 3)
+            sage: c = CompFullyAntiSym(ZZ, (1,2,3), 4)
+            sage: c._repr_symmetry()
+            ('Fully antisymmetric ', '')
 
         """
-        return "Fully antisymmetric " + str(self._nid) + "-indices" + \
-               " components w.r.t. " + str(self._frame)
+        return "Fully antisymmetric ", ""
 
     def _new_instance(self):
         r"""

src/sage/tensor/modules/ext_pow_free_module.py

@@ -436,7 +436,6 @@ def degree(self):
         """
         return self._degree
 
-
 #***********************************************************************