Free module bases

The class FreeModuleBasis implements bases on a free module \(M\) of finite rank over a commutative ring, while the class FreeModuleCoBasis implements the dual bases (i.e. bases of the dual module \(M^*\)).

AUTHORS:

  • Eric Gourgoulhon, Michal Bejger (2014-2015): initial version

  • Travis Scrimshaw (2016): ABC Basis_abstract and list functionality for bases (trac ticket #20770)

  • Eric Gourgoulhon (2018): some refactoring and more functionalities in the choice of symbols for basis elements (trac ticket #24792)

REFERENCES:

class sage.tensor.modules.free_module_basis.Basis_abstract(fmodule, symbol, latex_symbol, indices, latex_indices)

Bases: sage.structure.unique_representation.UniqueRepresentation, sage.structure.sage_object.SageObject

Abstract base class for (dual) bases of free modules.

free_module()

Return the free module of self.

EXAMPLES:

sage: M = FiniteRankFreeModule(QQ, 2, name='M', start_index=1)
sage: e = M.basis('e')
sage: e.free_module() is M
True
set_name(symbol, latex_symbol=None, indices=None, latex_indices=None, index_position='down')

Set (or change) the text name and LaTeX name of self.

INPUT:

  • symbol – either a string, to be used as a common base for the symbols of the elements of self, or a list of strings, representing the individual symbols of the elements of self

  • latex_symbol – (default: None) either a string, to be used as a common base for the LaTeX symbols of the elements of self, or a list of strings, representing the individual LaTeX symbols of the elements of self; if None, symbol is used in place of latex_symbol

  • indices – (default: None; used only if symbol is a single string) tuple of strings representing the indices labelling the elements of self; if None, the indices will be generated as integers within the range declared on the free module on which self is defined

  • latex_indices – (default: None) list of strings representing the indices for the LaTeX symbols of the elements of self; if None, indices is used instead

  • index_position – (default: 'down') determines the position of the indices labelling the individual elements of self; can be either 'down' or 'up'

EXAMPLES:

sage: M = FiniteRankFreeModule(ZZ, 3, name='M')
sage: e = M.basis('e'); e
Basis (e_0,e_1,e_2) on the Rank-3 free module M over the Integer Ring
sage: e.set_name('f'); e
Basis (f_0,f_1,f_2) on the Rank-3 free module M over the Integer Ring
sage: e.set_name(['a', 'b', 'c']); e
Basis (a,b,c) on the Rank-3 free module M over the Integer Ring
sage: e.set_name('e', indices=['x', 'y', 'z']); e
Basis (e_x,e_y,e_z) on the Rank-3 free module M over the Integer Ring
sage: e.set_name('e', index_position='up'); e
Basis (e^0,e^1,e^2) on the Rank-3 free module M over the Integer Ring
sage: latex(e)
\left(e^{0},e^{1},e^{2}\right)
sage: e.set_name('e', latex_symbol=r'\epsilon'); e
Basis (e_0,e_1,e_2) on the Rank-3 free module M over the Integer Ring
sage: latex(e)
\left(\epsilon_{0},\epsilon_{1},\epsilon_{2}\right)
sage: e.set_name('e', latex_symbol=[r'\alpha', r'\beta', r'\gamma'])
sage: latex(e)
\left(\alpha,\beta,\gamma\right)
sage: e.set_name('e', latex_symbol='E',
....:            latex_indices=[r'\alpha', r'\beta', r'\gamma'])
sage: latex(e)
\left(E_{\alpha},E_{\beta},E_{\gamma}\right)
sage: e.set_name('e') # back to the default
class sage.tensor.modules.free_module_basis.FreeModuleBasis(fmodule, symbol, latex_symbol=None, indices=None, latex_indices=None, symbol_dual=None, latex_symbol_dual=None)

Bases: sage.tensor.modules.free_module_basis.Basis_abstract

Basis of a free module over a commutative ring \(R\).

INPUT:

  • fmodule – free module \(M\) (as an instance of FiniteRankFreeModule)

  • symbol – either a string, to be used as a common base for the symbols of the elements of the basis, or a tuple of strings, representing the individual symbols of the elements of the basis

  • latex_symbol – (default: None) either a string, to be used as a common base for the LaTeX symbols of the elements of the basis, or a tuple of strings, representing the individual LaTeX symbols of the elements of the basis; if None, symbol is used in place of latex_symbol

  • indices – (default: None; used only if symbol is a single string) tuple of strings representing the indices labelling the elements of the basis; if None, the indices will be generated as integers within the range declared on fmodule

  • latex_indices – (default: None) tuple of strings representing the indices for the LaTeX symbols of the elements of the basis; if None, indices is used instead

  • symbol_dual – (default: None) same as symbol but for the dual basis; if None, symbol must be a string and is used for the common base of the symbols of the elements of the dual basis

  • latex_symbol_dual – (default: None) same as latex_symbol but for the dual basis

EXAMPLES:

A basis on a rank-3 free module over \(\ZZ\):

sage: M0 = FiniteRankFreeModule(ZZ, 3, name='M_0')
sage: from sage.tensor.modules.free_module_basis import FreeModuleBasis
sage: e = FreeModuleBasis(M0, 'e') ; e
Basis (e_0,e_1,e_2) on the Rank-3 free module M_0 over the Integer Ring

Instead of importing FreeModuleBasis in the global name space, it is recommended to use the module’s method basis():

sage: M = FiniteRankFreeModule(ZZ, 3, name='M')
sage: e = M.basis('e') ; e
Basis (e_0,e_1,e_2) on the Rank-3 free module M over the Integer Ring

The individual elements constituting the basis are accessed via the square bracket operator:

sage: e[0]
Element e_0 of the Rank-3 free module M over the Integer Ring
sage: e[0] in M
True

The slice operator : can be used to access to more than one element:

sage: e[0:2]
(Element e_0 of the Rank-3 free module M over the Integer Ring,
 Element e_1 of the Rank-3 free module M over the Integer Ring)
sage: e[:]
(Element e_0 of the Rank-3 free module M over the Integer Ring,
 Element e_1 of the Rank-3 free module M over the Integer Ring,
 Element e_2 of the Rank-3 free module M over the Integer Ring)

The LaTeX symbol can be set explicitly:

sage: latex(e)
\left(e_{0},e_{1},e_{2}\right)
sage: eps = M.basis('eps', latex_symbol=r'\epsilon') ; eps
Basis (eps_0,eps_1,eps_2) on the Rank-3 free module M over the Integer
 Ring
sage: latex(eps)
\left(\epsilon_{0},\epsilon_{1},\epsilon_{2}\right)

The individual elements of the basis are labelled according the parameter start_index provided at the free module construction:

sage: M = FiniteRankFreeModule(ZZ, 3, name='M', start_index=1)
sage: e = M.basis('e') ; e
Basis (e_1,e_2,e_3) on the Rank-3 free module M over the Integer Ring
sage: e[1]
Element e_1 of the Rank-3 free module M over the Integer Ring

It is also possible to fully customize the labels, via the argument indices:

sage: f = M.basis('f', indices=('x', 'y', 'z')); f
Basis (f_x,f_y,f_z) on the Rank-3 free module M over the Integer Ring
sage: f[1]
Element f_x of the Rank-3 free module M over the Integer Ring

The symbol of each element of the basis can also be freely chosen, by providing a tuple of symbols as the first argument of basis; it is then mandatory to specify some symbols for the dual basis as well:

sage: g = M.basis(('a', 'b', 'c'), symbol_dual=('A', 'B', 'C')); g
Basis (a,b,c) on the Rank-3 free module M over the Integer Ring
sage: g[1]
Element a of the Rank-3 free module M over the Integer Ring
sage: g.dual_basis()[1]
Linear form A on the Rank-3 free module M over the Integer Ring
dual_basis()

Return the basis dual to self.

OUTPUT:

EXAMPLES:

Dual basis on a rank-3 free module:

sage: M = FiniteRankFreeModule(ZZ, 3, name='M', start_index=1)
sage: e = M.basis('e') ; e
Basis (e_1,e_2,e_3) on the Rank-3 free module M over the Integer Ring
sage: f = e.dual_basis() ; f
Dual basis (e^1,e^2,e^3) on the Rank-3 free module M over the Integer Ring

Let us check that the elements of f are elements of the dual of M:

sage: f[1] in M.dual()
True
sage: f[1]
Linear form e^1 on the Rank-3 free module M over the Integer Ring

and that f is indeed the dual of e:

sage: f[1](e[1]), f[1](e[2]), f[1](e[3])
(1, 0, 0)
sage: f[2](e[1]), f[2](e[2]), f[2](e[3])
(0, 1, 0)
sage: f[3](e[1]), f[3](e[2]), f[3](e[3])
(0, 0, 1)
module()

Return the free module on which the basis is defined.

OUTPUT:

EXAMPLES:

sage: M = FiniteRankFreeModule(ZZ, 3, name='M')
sage: e = M.basis('e')
sage: e.module()
Rank-3 free module M over the Integer Ring
sage: e.module() is M
True
new_basis(change_of_basis, symbol, latex_symbol=None, indices=None, latex_indices=None, symbol_dual=None, latex_symbol_dual=None)

Define a new module basis from self.

The new basis is defined by means of a module automorphism.

INPUT:

  • change_of_basis – instance of FreeModuleAutomorphism describing the automorphism \(P\) that relates the current basis \((e_i)\) (described by self) to the new basis \((n_i)\) according to \(n_i = P(e_i)\)

  • symbol – either a string, to be used as a common base for the symbols of the elements of the basis, or a tuple of strings, representing the individual symbols of the elements of the basis

  • latex_symbol – (default: None) either a string, to be used as a common base for the LaTeX symbols of the elements of the basis, or a tuple of strings, representing the individual LaTeX symbols of the elements of the basis; if None, symbol is used in place of latex_symbol

  • indices – (default: None; used only if symbol is a single string) tuple of strings representing the indices labelling the elements of the basis; if None, the indices will be generated as integers within the range declared on the free module on which self is defined

  • latex_indices – (default: None) tuple of strings representing the indices for the LaTeX symbols of the elements of the basis; if None, indices is used instead

  • symbol_dual – (default: None) same as symbol but for the dual basis; if None, symbol must be a string and is used for the common base of the symbols of the elements of the dual basis

  • latex_symbol_dual – (default: None) same as latex_symbol but for the dual basis

OUTPUT:

EXAMPLES:

Change of basis on a vector space of dimension 2:

sage: M = FiniteRankFreeModule(QQ, 2, name='M', start_index=1)
sage: e = M.basis('e')
sage: a = M.automorphism()
sage: a[:] = [[1, 2], [-1, 3]]
sage: f = e.new_basis(a, 'f') ; f
Basis (f_1,f_2) on the 2-dimensional vector space M over the
 Rational Field
sage: f[1].display()
f_1 = e_1 - e_2
sage: f[2].display()
f_2 = 2 e_1 + 3 e_2
sage: e[1].display(f)
e_1 = 3/5 f_1 + 1/5 f_2
sage: e[2].display(f)
e_2 = -2/5 f_1 + 1/5 f_2

Use of some keyword arguments:

sage: b = e.new_basis(a, 'b', indices=('x', 'y'),
....:                 symbol_dual=('A', 'B'))
sage: b
Basis (b_x,b_y) on the 2-dimensional vector space M over the
 Rational Field
sage: b.dual_basis()
Dual basis (A,B) on the 2-dimensional vector space M over the
 Rational Field
class sage.tensor.modules.free_module_basis.FreeModuleCoBasis(basis, symbol, latex_symbol=None, indices=None, latex_indices=None)

Bases: sage.tensor.modules.free_module_basis.Basis_abstract

Dual basis of a free module over a commutative ring.

INPUT:

  • basis – basis of a free module \(M\) of which self is the dual (must be an instance of FreeModuleBasis)

  • symbol – either a string, to be used as a common base for the symbols of the elements of the cobasis, or a tuple of strings, representing the individual symbols of the elements of the cobasis

  • latex_symbol – (default: None) either a string, to be used as a common base for the LaTeX symbols of the elements of the cobasis, or a tuple of strings, representing the individual LaTeX symbols of the elements of the cobasis; if None, symbol is used in place of latex_symbol

  • indices – (default: None; used only if symbol is a single string) tuple of strings representing the indices labelling the elements of the cobasis; if None, the indices will be generated as integers within the range declared on the free module on which the cobasis is defined

  • latex_indices – (default: None) tuple of strings representing the indices for the LaTeX symbols of the elements of the cobasis; if None, indices is used instead

EXAMPLES:

Dual basis on a rank-3 free module:

sage: M = FiniteRankFreeModule(ZZ, 3, name='M', start_index=1)
sage: e = M.basis('e') ; e
Basis (e_1,e_2,e_3) on the Rank-3 free module M over the Integer Ring
sage: from sage.tensor.modules.free_module_basis import FreeModuleCoBasis
sage: f = FreeModuleCoBasis(e, 'f') ; f
Dual basis (f^1,f^2,f^3) on the Rank-3 free module M over the Integer Ring

Instead of importing FreeModuleCoBasis in the global name space, it is recommended to use the method dual_basis() of the basis e:

sage: f = e.dual_basis() ; f
Dual basis (e^1,e^2,e^3) on the Rank-3 free module M over the Integer Ring

Let us check that the elements of f are in the dual of M:

sage: f[1]
Linear form e^1 on the Rank-3 free module M over the Integer Ring
sage: f[1] in M.dual()
True

and that f is indeed the dual of e:

sage: f[1](e[1]), f[1](e[2]), f[1](e[3])
(1, 0, 0)
sage: f[2](e[1]), f[2](e[2]), f[2](e[3])
(0, 1, 0)
sage: f[3](e[1]), f[3](e[2]), f[3](e[3])
(0, 0, 1)