Vector Frames

The class VectorFrame implements vector frames on differentiable manifolds. By vector frame, it is meant a field \(e\) on some differentiable manifold \(U\) endowed with a differentiable map \(\Phi: U \rightarrow M\) to a differentiable manifold \(M\) such that for each \(p\in U\), \(e(p)\) is a vector basis of the tangent space \(T_{\Phi(p)}M\).

The standard case of a vector frame on \(U\) 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\)).

A derived class of VectorFrame is CoordFrame; it regards the vector frames associated with a chart, i.e. the so-called coordinate bases.

The vector frame duals, i.e. the coframes, are implemented via the class CoFrame. The derived class CoordCoFrame is devoted to coframes deriving from a chart.

AUTHORS:

  • Eric Gourgoulhon, Michal Bejger (2013-2015): initial version
  • Travis Scrimshaw (2016): review tweaks
  • Eric Gourgoulhon (2018): some refactoring and more functionalities in the choice of symbols for vector frame elements (trac ticket #24792)

REFERENCES:

EXAMPLES:

Defining a vector frame on a 3-dimensional manifold:

sage: M = Manifold(3, 'M')
sage: X.<x,y,z> = M.chart()
sage: e = M.vector_frame('e') ; e
Vector frame (M, (e_0,e_1,e_2))
sage: latex(e)
\left(M, \left(e_{0},e_{1},e_{2}\right)\right)

The first frame defined on a manifold is its default frame; in the present case it is the coordinate frame defined when introducing the chart X:

sage: M.default_frame()
Coordinate frame (M, (d/dx,d/dy,d/dz))

The default frame can be changed via the method set_default_frame():

sage: M.set_default_frame(e)
sage: M.default_frame()
Vector frame (M, (e_0,e_1,e_2))

The elements of a vector frame are vector fields on the manifold:

sage: for vec in e:
....:     print(vec)
....:
Vector field e_0 on the 3-dimensional differentiable manifold M
Vector field e_1 on the 3-dimensional differentiable manifold M
Vector field e_2 on the 3-dimensional differentiable manifold M

Each element of a vector frame can be accessed by its index:

sage: e[0]
Vector field e_0 on the 3-dimensional differentiable manifold M

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

sage: e[0:2]
(Vector field e_0 on the 3-dimensional differentiable manifold M,
 Vector field e_1 on the 3-dimensional differentiable manifold M)
sage: e[:]
(Vector field e_0 on the 3-dimensional differentiable manifold M,
 Vector field e_1 on the 3-dimensional differentiable manifold M,
 Vector field e_2 on the 3-dimensional differentiable manifold M)

The index range depends on the starting index defined on the manifold:

sage: M = Manifold(3, 'M', start_index=1)
sage: X.<x,y,z> = M.chart()
sage: e = M.vector_frame('e')
sage: [e[i] for i in M.irange()]
[Vector field e_1 on the 3-dimensional differentiable manifold M,
 Vector field e_2 on the 3-dimensional differentiable manifold M,
 Vector field e_3 on the 3-dimensional differentiable manifold M]
sage: e[1], e[2], e[3]
(Vector field e_1 on the 3-dimensional differentiable manifold M,
 Vector field e_2 on the 3-dimensional differentiable manifold M,
 Vector field e_3 on the 3-dimensional differentiable manifold M)

Let us check that the vector fields e[i] are the frame vectors from their components with respect to the frame \(e\):

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

Defining a vector frame on a manifold automatically creates the dual coframe, which, by default, bares the same name (here \(e\)):

sage: M.coframes()
[Coordinate coframe (M, (dx,dy,dz)), Coframe (M, (e^1,e^2,e^3))]
sage: f = M.coframes()[1] ; f
Coframe (M, (e^1,e^2,e^3))
sage: f is e.coframe()
True

Each element of the coframe is a 1-form:

sage: f[1], f[2], f[3]
(1-form e^1 on the 3-dimensional differentiable manifold M,
1-form e^2 on the 3-dimensional differentiable manifold M,
1-form e^3 on the 3-dimensional differentiable manifold M)
sage: latex(f[1]), latex(f[2]), latex(f[3])
(e^{1}, e^{2}, e^{3})

Let us check that the coframe \((e^i)\) is indeed the dual of the vector frame \((e_i)\):

sage: f[1](e[1]) # the 1-form e^1 applied to the vector field e_1
Scalar field e^1(e_1) on the 3-dimensional differentiable manifold M
sage: f[1](e[1]).expr() # the explicit expression of e^1(e_1)
1
sage: f[1](e[1]).expr(), f[1](e[2]).expr(), f[1](e[3]).expr()
(1, 0, 0)
sage: f[2](e[1]).expr(), f[2](e[2]).expr(), f[2](e[3]).expr()
(0, 1, 0)
sage: f[3](e[1]).expr(), f[3](e[2]).expr(), f[3](e[3]).expr()
(0, 0, 1)

The coordinate frame associated to spherical coordinates of the sphere \(S^2\):

sage: M = Manifold(2, 'S^2', start_index=1) # Part of S^2 covered by spherical coord.
sage: c_spher.<th,ph> = M.chart(r'th:[0,pi]:\theta ph:[0,2*pi):\phi')
sage: b = M.default_frame() ; b
Coordinate frame (S^2, (d/dth,d/dph))
sage: b[1]
Vector field d/dth on the 2-dimensional differentiable manifold S^2
sage: b[2]
Vector field d/dph on the 2-dimensional differentiable manifold S^2

The orthonormal frame constructed from the coordinate frame:

sage: change_frame = M.automorphism_field()
sage: change_frame[:] = [[1,0], [0, 1/sin(th)]]
sage: e = b.new_frame(change_frame, 'e') ; e
Vector frame (S^2, (e_1,e_2))
sage: e[1][:]
[1, 0]
sage: e[2][:]
[0, 1/sin(th)]

The change-of-frame automorphisms and their matrices:

sage: M.change_of_frame(c_spher.frame(), e)
Field of tangent-space automorphisms on the 2-dimensional
 differentiable manifold S^2
sage: M.change_of_frame(c_spher.frame(), e)[:]
[        1         0]
[        0 1/sin(th)]
sage: M.change_of_frame(e, c_spher.frame())
Field of tangent-space automorphisms on the 2-dimensional
 differentiable manifold S^2
sage: M.change_of_frame(e, c_spher.frame())[:]
[      1       0]
[      0 sin(th)]
sage.manifolds.differentiable.vectorframe.CoFrame

Coframe on a differentiable manifold.

By coframe, it is meant a field \(f\) on some differentiable manifold \(U\) endowed with a differentiable map \(\Phi: U \rightarrow M\) to a differentiable manifold \(M\) such that for each \(p\in U\), \(f(p)\) is a basis of the vector space \(T^*_{\Phi(p)}M\) (the dual to the tangent space \(T_{\Phi(p)}M\)).

The standard case of a coframe on \(U\) 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\)).

INPUT:

  • frame – the vector frame dual to the coframe
  • symbol – either a string, to be used as a common base for the symbols of the 1-forms constituting the coframe, or a tuple of strings, representing the individual symbols of the 1-forms
  • latex_symbol – (default: None) either a string, to be used as a common base for the LaTeX symbols of the 1-forms constituting the coframe, or a tuple of strings, representing the individual LaTeX symbols of the 1-forms; 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 1-forms of the coframe; if None, the indices will be generated as integers within the range declared on the coframe’s domain
  • latex_indices – (default: None) tuple of strings representing the indices for the LaTeX symbols of the 1-forms of the coframe; if None, indices is used instead

EXAMPLES:

Coframe on a 3-dimensional manifold:

sage: M = Manifold(3, 'M', start_index=1)
sage: X.<x,y,z> = M.chart()
sage: v = M.vector_frame('v')
sage: from sage.manifolds.differentiable.vectorframe import CoFrame
sage: e = CoFrame(v, 'e') ; e
Coframe (M, (e^1,e^2,e^3))

Instead of importing CoFrame in the global namespace, the coframe can be obtained by means of the method dual_basis(); the symbol is then the same as that of the frame:

sage: a = v.dual_basis() ; a
Coframe (M, (v^1,v^2,v^3))
sage: a[1] == e[1]
True
sage: a[1] is e[1]
False
sage: e[1].display(v)
e^1 = v^1

The 1-forms composing the coframe are obtained via the operator []:

sage: e[1], e[2], e[3]
(1-form e^1 on the 3-dimensional differentiable manifold M,
 1-form e^2 on the 3-dimensional differentiable manifold M,
 1-form e^3 on the 3-dimensional differentiable manifold M)

Checking that \(e\) is the dual of \(v\):

sage: e[1](v[1]).expr(), e[1](v[2]).expr(), e[1](v[3]).expr()
(1, 0, 0)
sage: e[2](v[1]).expr(), e[2](v[2]).expr(), e[2](v[3]).expr()
(0, 1, 0)
sage: e[3](v[1]).expr(), e[3](v[2]).expr(), e[3](v[3]).expr()
(0, 0, 1)
sage.manifolds.differentiable.vectorframe.CoordCoFrame

Coordinate coframe on a differentiable manifold.

By coordinate coframe, it is meant the \(n\)-tuple of the differentials of the coordinates of some chart on the manifold, with \(n\) being the manifold’s dimension.

INPUT:

  • coord_frame – coordinate frame dual to the coordinate coframe
  • symbol – either a string, to be used as a common base for the symbols of the 1-forms constituting the coframe, or a tuple of strings, representing the individual symbols of the 1-forms
  • latex_symbol – (default: None) either a string, to be used as a common base for the LaTeX symbols of the 1-forms constituting the coframe, or a tuple of strings, representing the individual LaTeX symbols of the 1-forms; 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 1-forms of the coframe; if None, the indices will be generated as integers within the range declared on the vector frame’s domain
  • latex_indices – (default: None) tuple of strings representing the indices for the LaTeX symbols of the 1-forms of the coframe; if None, indices is used instead

EXAMPLES:

Coordinate coframe on a 3-dimensional manifold:

sage: M = Manifold(3, 'M', start_index=1)
sage: X.<x,y,z> = M.chart()
sage: M.frames()
[Coordinate frame (M, (d/dx,d/dy,d/dz))]
sage: M.coframes()
[Coordinate coframe (M, (dx,dy,dz))]
sage: dX = M.coframes()[0] ; dX
Coordinate coframe (M, (dx,dy,dz))

The 1-forms composing the coframe are obtained via the operator []:

sage: dX[1]
1-form dx on the 3-dimensional differentiable manifold M
sage: dX[2]
1-form dy on the 3-dimensional differentiable manifold M
sage: dX[3]
1-form dz on the 3-dimensional differentiable manifold M
sage: dX[1][:]
[1, 0, 0]
sage: dX[2][:]
[0, 1, 0]
sage: dX[3][:]
[0, 0, 1]

The coframe is the dual of the coordinate frame:

sage: e = X.frame() ; e
Coordinate frame (M, (d/dx,d/dy,d/dz))
sage: dX[1](e[1]).expr(), dX[1](e[2]).expr(), dX[1](e[3]).expr()
(1, 0, 0)
sage: dX[2](e[1]).expr(), dX[2](e[2]).expr(), dX[2](e[3]).expr()
(0, 1, 0)
sage: dX[3](e[1]).expr(), dX[3](e[2]).expr(), dX[3](e[3]).expr()
(0, 0, 1)

Each 1-form of a coordinate coframe is closed:

sage: dX[1].exterior_derivative()
2-form ddx on the 3-dimensional differentiable manifold M
sage: dX[1].exterior_derivative() == 0
True
sage.manifolds.differentiable.vectorframe.CoordFrame

Coordinate frame on a differentiable manifold.

By coordinate frame, it is meant a vector frame on a differentiable manifold \(M\) that is associated to a coordinate chart on \(M\).

INPUT:

  • chart – the chart defining the coordinates

EXAMPLES:

The coordinate frame associated to spherical coordinates of the sphere \(S^2\):

sage: M = Manifold(2, 'S^2', start_index=1)  # Part of S^2 covered by spherical coord.
sage: M.chart(r'th:[0,pi]:\theta ph:[0,2*pi):\phi')
Chart (S^2, (th, ph))
sage: b = M.default_frame()
sage: b
Coordinate frame (S^2, (d/dth,d/dph))
sage: b[1]
Vector field d/dth on the 2-dimensional differentiable manifold S^2
sage: b[2]
Vector field d/dph on the 2-dimensional differentiable manifold S^2
sage: latex(b)
\left(S^2, \left(\frac{\partial}{\partial {\theta} },\frac{\partial}{\partial {\phi} }\right)\right)
sage.manifolds.differentiable.vectorframe.VectorFrame

Vector frame on a differentiable manifold.

By vector frame, it is meant a field \(e\) on some differentiable manifold \(U\) endowed with a differentiable map \(\Phi: U\rightarrow M\) to a differentiable manifold \(M\) such that for each \(p\in U\), \(e(p)\) is a vector basis of the tangent space \(T_{\Phi(p)}M\).

The standard case of a vector frame on \(U\) 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\)).

For each instanciation of a vector frame, a coframe is automatically created, as an instance of the class CoFrame. It is returned by the method coframe().

INPUT:

  • vector_field_module – free module \(\mathfrak{X}(U, \Phi)\) of vector fields along \(U\) with values on \(M \supset \Phi(U)\)
  • symbol – either a string, to be used as a common base for the symbols of the vector fields constituting the vector frame, or a tuple of strings, representing the individual symbols of the vector fields
  • latex_symbol – (default: None) either a string, to be used as a common base for the LaTeX symbols of the vector fields constituting the vector frame, or a tuple of strings, representing the individual LaTeX symbols of the vector fields; if None, symbol is used in place of latex_symbol
  • from_frame – (default: None) vector frame \(\tilde e\) on the codomain \(M\) of the destination map \(\Phi\); the constructed frame \(e\) is then such that \(\forall p \in U, e(p) = \tilde{e}(\Phi(p))\)
  • indices – (default: None; used only if symbol is a single string) tuple of strings representing the indices labelling the vector fields of the frame; if None, the indices will be generated as integers within the range declared on the vector frame’s domain
  • latex_indices – (default: None) tuple of strings representing the indices for the LaTeX symbols of the vector fields; if None, indices is used instead
  • symbol_dual – (default: None) same as symbol but for the dual coframe; if None, symbol must be a string and is used for the common base of the symbols of the elements of the dual coframe
  • latex_symbol_dual – (default: None) same as latex_symbol but for the dual coframe

EXAMPLES:

Defining a vector frame on a 3-dimensional manifold:

sage: M = Manifold(3, 'M', start_index=1)
sage: X.<x,y,z> = M.chart()
sage: e = M.vector_frame('e') ; e
Vector frame (M, (e_1,e_2,e_3))
sage: latex(e)
\left(M, \left(e_{1},e_{2},e_{3}\right)\right)

The individual elements of the vector frame are accessed via square brackets, with the possibility to invoke the slice operator ‘:’ to get more than a single element:

sage: e[2]
Vector field e_2 on the 3-dimensional differentiable manifold M
sage: e[1:3]
(Vector field e_1 on the 3-dimensional differentiable manifold M,
 Vector field e_2 on the 3-dimensional differentiable manifold M)
sage: e[:]
(Vector field e_1 on the 3-dimensional differentiable manifold M,
 Vector field e_2 on the 3-dimensional differentiable manifold M,
 Vector field e_3 on the 3-dimensional differentiable manifold M)

The LaTeX symbol can be specified:

sage: E = M.vector_frame('E', latex_symbol=r"\epsilon")
sage: latex(E)
\left(M, \left(\epsilon_{1},\epsilon_{2},\epsilon_{3}\right)\right)

By default, the elements of the vector frame are labelled by integers within the range specified at the manifold declaration. It is however possible to fully customize the labels, via the argument indices:

sage: u = M.vector_frame('u', indices=('x', 'y', 'z')) ; u
Vector frame (M, (u_x,u_y,u_z))
sage: u[1]
Vector field u_x on the 3-dimensional differentiable manifold M
sage: u.coframe()
Coframe (M, (u^x,u^y,u^z))

The LaTeX format of the indices can be adjusted:

sage: v = M.vector_frame('v', indices=('a', 'b', 'c'),
....:                    latex_indices=(r'\alpha', r'\beta', r'\gamma'))
sage: v
Vector frame (M, (v_a,v_b,v_c))
sage: latex(v)
\left(M, \left(v_{\alpha},v_{\beta},v_{\gamma}\right)\right)
sage: latex(v.coframe())
\left(M, \left(v^{\alpha},v^{\beta},v^{\gamma}\right)\right)

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

sage: h = M.vector_frame(('a', 'b', 'c'), symbol_dual=('A', 'B', 'C'))
sage: h
Vector frame (M, (a,b,c))
sage: h[1]
Vector field a on the 3-dimensional differentiable manifold M
sage: h.coframe()
Coframe (M, (A,B,C))
sage: h.coframe()[1]
1-form A on the 3-dimensional differentiable manifold M

Example with a non-trivial map \(\Phi\) (see above); a vector frame along a curve:

sage: U = Manifold(1, 'U')  # open interval (-1,1) as a 1-dimensional manifold
sage: T.<t> = U.chart('t:(-1,1)')  # canonical chart on U
sage: Phi = U.diff_map(M, [cos(t), sin(t), t], name='Phi',
....:                  latex_name=r'\Phi')
sage: Phi
Differentiable map Phi from the 1-dimensional differentiable manifold U
 to the 3-dimensional differentiable manifold M
sage: f = U.vector_frame('f', dest_map=Phi) ; f
Vector frame (U, (f_1,f_2,f_3)) with values on the 3-dimensional
 differentiable manifold M
sage: f.domain()
1-dimensional differentiable manifold U
sage: f.ambient_domain()
3-dimensional differentiable manifold M

The value of the vector frame at a given point is a basis of the corresponding tangent space:

sage: p = U((0,), name='p') ; p
Point p on the 1-dimensional differentiable manifold U
sage: f.at(p)
Basis (f_1,f_2,f_3) on the Tangent space at Point Phi(p) on the
 3-dimensional differentiable manifold M

Vector frames are bases of free modules formed by vector fields:

sage: e.module()
Free module X(M) of vector fields on the 3-dimensional differentiable
 manifold M
sage: e.module().base_ring()
Algebra of differentiable scalar fields on the 3-dimensional
 differentiable manifold M
sage: e.module() is M.vector_field_module()
True
sage: e in M.vector_field_module().bases()
True
sage: f.module()
Free module X(U,Phi) of vector fields along the 1-dimensional
 differentiable manifold U mapped into the 3-dimensional differentiable
 manifold M
sage: f.module().base_ring()
Algebra of differentiable scalar fields on the 1-dimensional
 differentiable manifold U
sage: f.module() is U.vector_field_module(dest_map=Phi)
True
sage: f in U.vector_field_module(dest_map=Phi).bases()
True