Tensors on free modules of finite rank

[egourgoulhon]

Description

This ticket implements:

• tensor products of the type M\otimes ...\otimes M \otimes M* \otimes...\otimes M*
  where M is a free module of finite rank over a commutative ring R and M* is its dual (k factors of M and l factors of M*, say)
• the elements of the above tensor products, considered as tensors of type (k,l) on M, i.e. multilinear forms (M*)^k \times M^l --> R, thanks to the canonical isomorphism (M*)* = M (which holds since M is a free module of finite rank)
• the following tensor operations:
  • operations inherent to the module structure (addition, multiplication by a ring element)
  • tensor product of two tensors
  • tensor contraction
  • symmetry / antisymmetry handling (on subset of the tensor arguments or on all arguments)
  • exterior product of alternating forms
• morphisms of free modules of finite rank, with coercion of endomorphisms to/from type-(1,1) tensors

No distinguished basis is assumed on the free module M; on the contrary many bases can be introduced. Each tensor has then various representations, via its components in the various bases.

Motivation and context

The ticket has been motivated by tensors on smooth manifolds over R, within the
SageManifolds project. In this context, tensors on free modules appear at two levels:

• tensors on tangent spaces:
  • commutative ring R: real field R
  • free module M: tangent vector space at a given manifold's point
• tensor fields on a manifold:
  • commutative ring R: the algebra C^oo(U) of smooth functions U--> R, where U is a parallelizable open set of the manifold
  • free module M: the set X(U) of smooth vector fields on U (since U is parallelizable, this is a free module; its rank is the manifold's dimension)

Documentation

Apart from the numerous doctests in the code, some pieces of documentation are

• the tutorial worksheet posted here (a pdf version is here)
• the "tensors on free modules" reference manual; it can also be generated via the command sage -docbuild reference/tensor_free_modules html

See also this page.

Remarks

1. Although developed in the context of SageManifolds (ticket:14865), the ticket is self-contained and does not depend on other parts of SageManifolds. It this respect, it can be viewed as some attempt to include a first subset of SageManifolds in Sage, with a moderate size: the ticket comprises 14499 lines of Python code (most of them being doctests), while at present (version 0.6) SageManifolds contains 35157 lines of code.

2. The ticket follows Sage's !Parent/Element pattern and the (new) category framework. In particular, the ticket's free module class (FiniteRankFreeModule) passes the module TestSuite.

3. It turned out to be necessary to develop a new class to implement free modules of finite rank. Indeed, the category of free modules does not exist yet in Sage: only those of generic modules (Modules) or free modules with a distinguished basis (ModulesWithBasis) are available. Now, the tangent space at a given point of a manifold is a vector space without any distinguished basis (in other words, while the tangent space is isomorphic to Rⁿ, there is no canonical isomorphism, each isomorphism relying on the choice of some coordinate chart). The new class, FiniteRankFreeModule, does not rely on any distinguished basis. It inherits directly from Parent, with the category set to Modules(). In particular, it does not inherit from sage.modules.module.FreeModule_generic since the latter seems to assume a distinguished basis (cf. its method basis()).

CC: @simon-king-jena

Component: linear algebra

Keywords: free module, tensor, tensor product, days64

Author: Eric Gourgoulhon, Michal Bejger

Branch: 99f9ac5

Reviewer: Travis Scrimshaw

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

[egourgoulhon]

Changed author from egourgoulhon, mbejger to Eric Gourgoulhon, Michal Bejger

[sagetrac-git]

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

e34f29e

Minor modifications in tensor/modules, including the add of method _new_instance() to classes FreeModuleAltForm and FreeModuleLinForm

[sagetrac-git]

Changed commit from f8e9c3e to e34f29e

[jhpalmieri]

comment:4

Is there any connection and/or overlap between this ticket and #15726?

[egourgoulhon]

comment:5

This ticket implements tensor modules T^(k,l)(M) of a fixed type (k,l) over a free module M of finite rank, while #15726 implements the tensor algebra T(M), which is the direct sum of all T^(k,l)(M).

Another major difference is that here the base module M is a generic free module, while in #15726 M is a free module with a distinguished basis (the classes TensorModule and TensorAlgebra of #15726 inherit from class CombinatorialFreeModule, which assumes a distinguished basis). In the present ticket, an arbitrary number of bases can be introduced on the free module M, along with the change-of-basis automorphisms, and each tensor has various sets of components, one per basis.

Another difference may regard symmetry/antisymmetry handling: the tensors implemented in this ticket can have arbitrary symmetries and/or antisymmetries. The symmetries are taken into account to reduce the storage of tensor components and to optimize some computations, such as the tensor product. But maybe something similar is implemented in #15726.

[sagetrac-git]

Changed commit from e34f29e to 8b7bd60

[sagetrac-git]

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

8b7bd60

Updated 'tensors on free modules' to Sage 6.2

[sagetrac-git]

Changed commit from 8b7bd60 to 010c313

[sagetrac-git]

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

010c313

Minor improvements; coincides with SageManifolds as of 18 May 2014 (commit d488f8f807 on github)

[sagetrac-git]

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

267b6b9

Update to SageManifolds v0.5

[sagetrac-git]

Changed commit from 010c313 to 267b6b9

[egourgoulhon]

comment:10

This is now part of SageManifolds v0.5 (see ​this post on sage-devel and http://sagemanifolds.obspm.fr/changelog.html).

[sagetrac-git]

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

8f0878d

Added index notation for tensor contractions and symmetrizations

[sagetrac-git]

Changed commit from 267b6b9 to 8f0878d

[sagetrac-git]

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

d8f518f

Update to SageManifolds v0.6

[sagetrac-git]

Changed commit from 8f0878d to d8f518f

[egourgoulhon]

comment:19

The ticket has been updated to coincide with the pure algebraic part of SageManifolds v0.6. Changes are:
1/ The possibility to use index notations for denoting tensor contractions or symmetrizations: the indices have to be passed in LaTeX notations (possibly without {}) as a string inside the square bracket operator, e.g.

sage: S = A['^{ab}_{cd}']*B['^d_a'] # equivalent to S = A.contract(0, 3, B, 1, 0)

to denote the tensor S^b_c = A^ab_cd B^d_a ,

sage: S = A['^{(ab)}_{cd}']  # equivalent to S = A.symmetrize(0,1)

to denote the tensor S^ab_cd = A^(ab)_cd, and

sage: S = A['^{ab}_{[cd]}']  # equivalent to S = A.antisymmetrize(2,3)

to denote the tensor S^ab_cd = A^ab_[cd].
See this page and this one for more details.

2/ The code for tensor contractions has been completely rewritten; it is more efficient and allows now for multiple contractions (as in the first example above).

3/ The argument of methods symmetrize() and antisymmetrize() in the FreeModuleTensor class is now directly a sequence of index positions (and no longer a single list/tuple encapsulating such a sequence).

Besides, new examples have been provided on http://sagemanifolds.obspm.fr/examples.html; two of them are directly relevant to this ticket:

• tensors on free modules of finite rank (tutorial)
• vector-field modules on the 2-sphere (a concrete example of use)

[sagetrac-git]

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

af361f7

Fix a merge conflict in the reference manual w.r.t. the latest develop version of Sage

[sagetrac-git]

Changed commit from 278c94a to af361f7

[sagetrac-git]

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

8f11343

Merge #15916 into Sage 6.6.beta5 to solve a conflict in src/doc/en/reference/index.rst

[sagetrac-git]

Changed commit from af361f7 to 8f11343

[tscrim]

comment:59

I'm happy with the current version of this, so positive review. Thanks for your work on this!

[tscrim]

Changed keywords from free module, tensor, tensor product to free module, tensor, tensor product, days64

[vbraun]

comment:60

Doctests fail

[sagetrac-git]

Changed commit from 8f11343 to 99f9ac5

[sagetrac-git]

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

99f9ac5

Fix doctest because of new doc category.

[tscrim]

comment:62

This is the only (trivial) failure I can see.

[egourgoulhon]

comment:63

Replying to @tscrim:

This is the only (trivial) failure I can see.

In the patchbot log, there are many doctest failures but they pertain to other parts of Sage: all doctests of files in src/sage/tensor/modules (i.e. the sources of this ticket) pass. So I am puzzled: why the patchbot returns so many failures? Could it be that the ticket branch is based on Sage 6.6.beta5?

[tscrim]

comment:64

Replying to @egourgoulhon:

Replying to @tscrim:

This is the only (trivial) failure I can see.

In the patchbot log, there are many doctest failures but they pertain to other parts of Sage: all doctests of files in src/sage/tensor/modules (i.e. the sources of this ticket) pass. So I am puzzled: why the patchbot returns so many failures? Could it be that the ticket branch is based on Sage 6.6.beta5?

It has to do with file permissions on the patchbot account. They are harmless and not really errors as far as Sage is concerned, but comes from python IIRC.

[egourgoulhon]

comment:65

Replying to @tscrim:

Replying to @egourgoulhon:

Replying to @tscrim:

This is the only (trivial) failure I can see.

In the patchbot log, there are many doctest failures but they pertain to other parts of Sage: all doctests of files in src/sage/tensor/modules (i.e. the sources of this ticket) pass. So I am puzzled: why the patchbot returns so many failures? Could it be that the ticket branch is based on Sage 6.6.beta5?

It has to do with file permissions on the patchbot account. They are harmless and not really errors as far as Sage is concerned, but comes from python IIRC.

OK I see. Thank you Travis!

[vbraun]

Changed branch from public/tensor_modules-15916 to 99f9ac5

[fchapoton]

comment:67

sequel in #26392

[fchapoton]

Changed commit from 99f9ac5 to none