Submodules of TensorFreeModule defined by the symmetries of a Components object

[mkoeppe]

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:

• TensorFreeModule.isomorphism_with_fixed_basis #34427 TensorFreeModule.isomorphism_with_fixed_basis
• Make ExtPowerFreeModule a quotient of TensorFreeModule #30242 Make ExtPowerFreeModule a quotient of TensorFreeModule
• Refactor Components into parent & element #30307 Refactor Components into parent (a ModuleWithBasis) & element

Depends on #30300
Depends on #34424
Depends on #34451
Depends on #34474

CC: @egourgoulhon @tscrim @mjungmath @slel @honglizhaobob

Component: linear algebra

Author: Matthias Koeppe

Branch/Commit: fc66ad1

Reviewer: Eric Gourgoulhon

Issue created by migration from https://trac.sagemath.org/ticket/30229

[egourgoulhon]

comment:2

The current design of ExtPowerFreeModule, ExtPowerDualFreeModule and TensorFreeModule is such that they cannot have their own bases, although they are mathematically free modules and they inherit from FiniteRankFreeModule. This is because all the basis management is performed at the level of the base module. Indeed, any choice of basis in the base module gives birth uniquely to a basis in each of the tensor modules and exterior power modules.
For instance:

sage: M = FiniteRankFreeModule(ZZ, 2, name='M')
sage: e = M.basis('e')
sage: t = M.tensor((1, 1), name='t'); t
Type-(1,1) tensor t on the Rank-2 free module M over the Integer Ring

The components are set and displayed with respect to the basis e = (e_0, e_1) of the base module M and its dual basis (e^0, e^1):

sage: t[e, :] = [[1, 0], [-2, 0]]
sage: t.display(e)  # equivalent to t.display()
t = e_0*e^0 - 2 e_1*e^0
sage: t.components(e)
2-indices components w.r.t. Basis (e_0,e_1) on the Rank-2 free module M 
 over the Integer Ring

The same feature holds for ExtPowerDualFreeModule elements:

sage: a = M.alternating_form(2, name='a')
sage: a.parent()
2nd exterior power of the dual of the Rank-2 free module M over the Integer Ring
sage: a[e, 0, 1] = 3
sage: a.display(e)  # equivalent to a.display()
a = 3 e^0/\e^1
sage: a.components(e)
Fully antisymmetric 2-indices components w.r.t. Basis (e_0,e_1) on the Rank-2 
 free module M over the Integer Ring

If we introduce proper bases for the derived modules ExtPowerFreeModule, ExtPowerDualFreeModule and TensorFreeModule, then t.display() would become ambiguous: shall we want a display w.r.t. to the default basis of M or to the default basis of t.parent()? Moreover, the storage of components is currently performed with respect to bases of the base module. Introducing bases in the tensor modules shall of course not lead to duplicate storage.

If we keep this design (which I would favor at this stage), then, for the sake of clarity,

sage: A = M.exterior_power(2)
sage: A.basis('w')

shall return a NotImplementedError and not a TypeError, with a message like only bases on the base module are implemented.

[slel]

Description changed:

--- 
+++ 
@@ -1,16 +1,22 @@
+Setup:
 
 ```
-            sage: from sage.tensor.modules.ext_pow_free_module import ExtPowerFreeModule
-            sage: M = FiniteRankFreeModule(ZZ, 3, name='M')
-            sage: e = M.basis('e')
-            sage: A = ExtPowerFreeModule(M, 2) ; A
-            sage: A.basis('w')
-            TypeError: __init__() missing 1 required positional argument: 'degree'
+sage: from sage.tensor.modules.ext_pow_free_module import ExtPowerFreeModule
+sage: from sage.tensor.modules.tensor_free_module import TensorFreeModule
+sage: M = FiniteRankFreeModule(ZZ, 3, name='M')
+sage: e = M.basis('e')
+```
 
-        sage: M = FiniteRankFreeModule(ZZ, 3, name='M')
-        sage: e = M.basis('e')
-        sage: from sage.tensor.modules.tensor_free_module import TensorFreeModule
-        sage: T = TensorFreeModule(M, (1,2)) ; T
-        sage: T.basis('q')
-        TypeError: __init__() missing 1 required positional argument: 'tensor_type'
+Problems:
+
 ```
+sage: A = ExtPowerFreeModule(M, 2) ; A
+sage: A.basis('w')
+TypeError: __init__() missing 1 required positional argument: 'degree'
+```
+
+```
+sage: T = TensorFreeModule(M, (1,2)) ; T
+sage: T.basis('q')
+TypeError: __init__() missing 1 required positional argument: 'tensor_type'
+```

[mkoeppe]

comment:4

Thanks a lot for the explanation.

Yes, a NotImplementedError with a clear message would be an improvement.

It could also be considered whether these three classes should really be subclasses of FiniteRankFreeModule, or perhaps rather a new common baseclass.

[mkoeppe]

Description changed:

--- 
+++ 
@@ -11,12 +11,18 @@
 
 ```
 sage: A = ExtPowerFreeModule(M, 2) ; A
+2nd exterior power of the Rank-3 free module M over the Integer Ring
+sage: A.default_basis()
+No default basis has been defined on the 2nd exterior power of the Rank-3 free module M over the Integer Ring
 sage: A.basis('w')
 TypeError: __init__() missing 1 required positional argument: 'degree'
 ```
 
 ```
 sage: T = TensorFreeModule(M, (1,2)) ; T
+Free module of type-(1,2) tensors on the Rank-3 free module M over the Integer Ring
+sage: T.default_basis()
+No default basis has been defined on the Free module of type-(1,2) tensors on the Rank-3 free module M over the Integer Ring
 sage: T.basis('q')
 TypeError: __init__() missing 1 required positional argument: 'tensor_type'
 ```

[egourgoulhon]

Description changed:

--- 
+++ 
@@ -1,8 +1,6 @@
 Setup:
 
 ```
-sage: from sage.tensor.modules.ext_pow_free_module import ExtPowerFreeModule
-sage: from sage.tensor.modules.tensor_free_module import TensorFreeModule
 sage: M = FiniteRankFreeModule(ZZ, 3, name='M')
 sage: e = M.basis('e')
 ```
@@ -10,7 +8,7 @@
 Problems:
 
 ```
-sage: A = ExtPowerFreeModule(M, 2) ; A
+sage: A = M.exterior_power(2); A
 2nd exterior power of the Rank-3 free module M over the Integer Ring
 sage: A.default_basis()
 No default basis has been defined on the 2nd exterior power of the Rank-3 free module M over the Integer Ring
@@ -19,7 +17,7 @@
 ```
 
 ```
-sage: T = TensorFreeModule(M, (1,2)) ; T
+sage: T = M.tensor_module(1, 2); T
 Free module of type-(1,2) tensors on the Rank-3 free module M over the Integer Ring
 sage: T.default_basis()
 No default basis has been defined on the Free module of type-(1,2) tensors on the Rank-3 free module M over the Integer Ring

[egourgoulhon]

comment:6

Replying to @mkoeppe:

It could also be considered whether these three classes should really be subclasses of FiniteRankFreeModule, or perhaps rather a new common baseclass.

Yes, indeed!

[mkoeppe]

comment:7

Replying to @egourgoulhon:

all the basis management is performed at the level of the base module. Indeed, any choice of basis in the base module gives birth uniquely to a basis in each of the tensor modules and exterior power modules.

Given this, I am also wondering whether perhaps there should be a subclass of Basis_abstract that would make these bases explicit.

[mkoeppe]

Branch: u/mkoeppe/extpowerfreemodule__extpowerdualfreemodule__tensorfreemodule_cannot_create_a_basis

[mkoeppe]

Description changed:

--- 
+++ 
@@ -24,3 +24,7 @@
 sage: T.basis('q')
 TypeError: __init__() missing 1 required positional argument: 'tensor_type'
 ```
+
+On this ticket, we add a class `FreeModuleCompTensorBasis` that implements the standard basis of a tensor module (given a basis of the base module), indexed by `Component.non_redundant_index_generator()`.
+
+

[mkoeppe]

comment:9

Preliminary branch

---

New commits:

862aca8

WIP: Implement TensorFreeModule.basis with new class FreeModuleCompTensorBasis

[mkoeppe]

Commit: 862aca8

[sagetrac-git]

Changed commit from 862aca8 to 3bd0a8a

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

3bd0a8a

TensorFreeSubmodule_comp, TensorFreeSubmoduleBasis_comp: New

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,22 +1,8 @@
-Setup:
+Currently, `TensorFreeModule` does not have an interface to the bases that it uses implicitly, nor is it possible to create new bases for it.
 
 ```
 sage: M = FiniteRankFreeModule(ZZ, 3, name='M')
 sage: e = M.basis('e')
-```
-
-Problems:
-
-```
-sage: A = M.exterior_power(2); A
-2nd exterior power of the Rank-3 free module M over the Integer Ring
-sage: A.default_basis()
-No default basis has been defined on the 2nd exterior power of the Rank-3 free module M over the Integer Ring
-sage: A.basis('w')
-TypeError: __init__() missing 1 required positional argument: 'degree'
-```
-
-```
 sage: T = M.tensor_module(1, 2); T
 Free module of type-(1,2) tensors on the Rank-3 free module M over the Integer Ring
 sage: T.default_basis()
@@ -25,6 +11,10 @@
 TypeError: __init__() missing 1 required positional argument: 'tensor_type'
 ```
 
-On this ticket, we add a class `FreeModuleCompTensorBasis` that implements the standard basis of a tensor module (given a basis of the base module), indexed by `Component.non_redundant_index_generator()`.
+On this ticket, we add a subclass `TensorFreeSubmodule_comp` of `TensorFreeModule` that implements subspaces spanned by the tensors with prescribed symmetries. 
+
+It provides a `basis` method that returns an instance of the new class `TensorFreeSubmoduleBasis_comp`, which represents the standard basis corresponding to a given `Components` object.
+
+Also any `TensorFreeModule` provides a `basis` method that returns such a basis object.
 
 

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

c4d8d07

Move basis method to TensorFreeModule