SM_tutorial.sagews

%auto
typeset_mode(True, display=False)

SageManifolds tutorial

This worksheet provides a short introduction to SageManifolds (version 0.8).

It is released under the GNU General Public License version 3.

(c) Eric Gourgoulhon, Michal Bejger (2015)

The corresponding worksheet file can be downloaded from here.

 

Defining a manifold

The following assumes that the SageManifolds package is installed on your computer (see the download and installation instructions if not).

As an example let us define a differentiable manifold of dimension 3 over $\mathbb{R}$:

• The first argument, 3, is the manifold dimension. In SageManifolds, it can be any positive integer.
• The second argument, 'M', is a string defining the manifold's name; it may be different from the symbol set on the left-hand side of the = sign (here M): the latter is a mere Python variable name that refers to the manifold object in the computer memory, while 'M' identifies the manifold.
• The third argument, r'\mathcal{M}', is a string defining the LaTeX symbol to represent the manifold. Note the letter 'r' in front on the first quote: it indicates that the string is a raw one, so that the backslash character in \mathcal is considered as an ordinary character (otherwise, the backslash is used to escape some special characters).
• The fourth argument, start_index=1, defines the range of indices to be used for tensor components on the manifold: setting it to 1 means that indices will range in $\{1,2,3\}$. The default value is start_index=0.

If we ask for M, the LaTeX symbol is returned (provided the worksheet's Typeset box is selected):

M

$\mathcal{M}$

If we use the command print instead, we get a short description of the object:

print M

3-dimensional manifold 'M'

Via the command type, we get the type of the Python object corresponding to M (here the Python class Manifold_with_category):

type(M)

<class 'sage.geometry.manifolds.manifold.Manifold_with_category'>

The indices on the manifold are generated by the method irange(), to be used in loops:

for i in M.irange():
    print i,

1 2 3

If the parameter start_index had not been specified, the default range of the indices would have been $\{0,1,2\}$ instead:

M0 = Manifold(3, 'M', r'\mathcal{M}')
for i in M0.irange():
    print i,

0 1 2

Defining a chart on the manifold

Let us assume that the manifold $\mathcal{M}$ can be covered by a single chart (other cases are discussed below); the chart is declared as follows:

X.<x,y,z> = M.chart()

The writing .<x,y,z> in the left-hand side means that the Python variables x, y and z are set to the three coordinates of the chart. This allows one to refer subsequently to the coordinates by their names.

In this example, the function chart() has no arguments, which implies that the coordinate symbols will be 'x', 'y' and 'z' (i.e. exactly the characters set in the <...> operator) and that each coordinate range is $(-\infty,+\infty)$. For other cases, an argument must be passed to chart()  to specify the coordinate symbols and range, as well as the LaTeX symbols of the coordinates if the latter are different from the coordinate names (an example will be provided below).

print X

chart (M, (x, y, z))

The chart is displayed as a pair formed by the open set covered by it (here the whole manifold) and the coordinate names:

X

$\left(\mathcal{M},(x, y, z)\right)$

The coordinates can be accessed individually, by means of their indices, following the convention defined by start_index=1 in the manifold's definition:

X[1]

$x$

X[2]

$y$

X[3]

$z$

The full set of coordinates is obtained by means of the operator [:]:

X[:]

($x$, $y$, $z$)

Thanks to the operator <x,y,z> in the chart declaration, each coordinate can be accessed directly via its name:

z is X[3]

$\mathrm{True}$

Coordinates are Sage symbolic expressions:

type(z)

<type 'sage.symbolic.expression.Expression'>

Functions of the chart coordinates

Real-valued functions of the chart coordinates (mathematically speaking, functions defined on the chart codomain) are formed via the method function() acting on the chart:

f = X.function(x+y^2+z^3) ; f

$z^{3} + y^{2} + x$

f.display()

$\left(x, y, z\right) \mapsto z^{3} + y^{2} + x$

f(1,2,3)

$32$

They belong to SageManifolds class FunctionChart:

type(f)

<class 'sage.geometry.manifolds.chart.FunctionChart'>

and differ from Sage standard symbolic functions by automatic simplifications in all operations. For instance, adding the two symbolic functions

f0(x,y,z) = cos(x)^2 ; g0(x,y,z) = sin(x)^2

results in

f0 + g0

$\left( x, y, z \right) \ {\mapsto} \ \cos\left(x\right)^{2} + \sin\left(x\right)^{2}$

while the sum of the corresponding FunctionChart functions is automatically simplified:

f1 = X.function(cos(x)^2) ; g1 = X.function(sin(x)^2)
f1 + g1

$1$

To get the same output with symbolic functions, one has to call the method simplify_trig():

(f0 + g0).simplify_trig()

$\left( x, y, z \right) \ {\mapsto} \ 1$

Another difference regards the display; if we ask for the symbolic function f0, we get:

f0

$\left( x, y, z \right) \ {\mapsto} \ \cos\left(x\right)^{2}$

while if we ask for the chart function f1, we get only the coordinate expression:

f1

$\cos\left(x\right)^{2}$

To get an output similar to that of f0, one should call the method display():

f1.display()

$\left(x, y, z\right) \mapsto \cos\left(x\right)^{2}$

Note that the method expr() returns the corresponding Sage symbolic expression:

f1.expr()

$\cos\left(x\right)^{2}$

type(f1.expr())

<type 'sage.symbolic.expression.Expression'>

Introducing a second chart on the manifold

Let us first consider an open subset of $\mathcal{M}$, for instance the complement $U$ of the region defined by $\{y=0, x\geq 0\}$ (note that (y!=0, x<0) stands for $y\not=0$ OR $x<0$; the condition $y\not=0$ AND $x<0$ would have been written [y!=0, x<0] instead):

U = M.open_subset('U', coord_def={X: (y!=0, x<0)})

Let us call X_U the restriction of the chart X to the open subset $U$:

X_U = X.restrict(U) ; X_U

$\left(U,(x, y, z)\right)$

We introduce another chart on $U$, with spherical-type coordinates $(r,\theta,\phi)$:

Y.<r,th,ph> = U.chart(r'r:(0,+oo) th:(0,pi):\theta ph:(0,2*pi):\phi') ; Y

$\left(U,(r, {\theta}, {\phi})\right)$

The function chart() has now some argument; it is a string, which contains specific LaTeX symbols, hence the prefix 'r' to it (for raw string). It also contains the coordinate ranges, since they are different from the default value, which is $(-\infty, +\infty)$. For a given coordinate, the various fields are separated by the character ':' and a space character separates the coordinates. Note that for $r$, there is only two fields, since the LaTeX symbol has not to be specified. The LaTeX symbols are used for the outputs:

th, ph

(${\theta}$, ${\phi}$)

Y[2], Y[3]

(${\theta}$, ${\phi}$)

The declared coordinate ranges are now known to Sage, as we may check by means of the command assumptions():

assumptions()

[$\text{\texttt{x{ }is{ }real}}$, $\text{\texttt{y{ }is{ }real}}$, $\text{\texttt{z{ }is{ }real}}$, $\text{\texttt{r{ }is{ }real}}$, $r > 0$, $\text{\texttt{th{ }is{ }real}}$, ${\theta} > 0$, ${\theta} < \pi$, $\text{\texttt{ph{ }is{ }real}}$, ${\phi} > 0$, ${\phi} < 2 \, \pi$]

They are used in simplifications:

simplify(abs(r))

$r$

simplify(abs(x)) # no simplification occurs since x can take any value in R

${\left| x \right|}$

After having been declared, the chart Y can be fully specified by its relation to the chart X_U, via a transition map:

transit_Y_to_X = Y.transition_map(X_U, [r*sin(th)*cos(ph), r*sin(th)*sin(ph), r*cos(th)])

transit_Y_to_X

$\left(U,(r, {\theta}, {\phi})\right) \rightarrow \left(U,(x, y, z)\right)$

transit_Y_to_X.display()

$\left\{\begin{array}{lcl} x & = & r \cos\left({\phi}\right) \sin\left({\theta}\right) \\ y & = & r \sin\left({\phi}\right) \sin\left({\theta}\right) \\ z & = & r \cos\left({\theta}\right) \end{array}\right.$

The inverse of the transition map can be specified by means of the method set_inverse():

transit_Y_to_X.set_inverse(sqrt(x^2+y^2+z^2), atan2(sqrt(x^2+y^2),z), atan2(y, x))
transit_Y_to_X.inverse().display()

Check of the inverse coordinate transformation: r == r th == arctan2(r*sin(th), r*cos(th)) ph == arctan2(r*sin(ph)*sin(th), r*cos(ph)*sin(th)) x == x y == y z == z

$\left\{\begin{array}{lcl} r & = & \sqrt{x^{2} + y^{2} + z^{2}} \\ {\theta} & = & \arctan\left(\sqrt{x^{2} + y^{2}}, z\right) \\ {\phi} & = & \arctan\left(y, x\right) \end{array}\right.$

The check is passed, although some simplifications related to the arctan2 function are not performed.

At this stage, the manifold's atlas (the "user atlas", not the maximal atlas!) contains three charts:

M.atlas()

[$\left(\mathcal{M},(x, y, z)\right)$, $\left(U,(x, y, z)\right)$, $\left(U,(r, {\theta}, {\phi})\right)$]

The first chart defined on the manifold is considered as the manifold's default chart (it can be changed by the method set_default_chart()):

M.default_chart()

$\left(\mathcal{M},(x, y, z)\right)$

Each open subset has its own atlas:

U.atlas()

[$\left(U,(x, y, z)\right)$, $\left(U,(r, {\theta}, {\phi})\right)$]

U.default_chart()

$\left(U,(x, y, z)\right)$

We can draw the chart $Y$ in terms of the chart $X$: the plot shows lines of constant coordinates from the $Y$ chart in a "Cartesian frame" based on the $X$ coordinates:

Y.plot(X)

3D rendering not yet implemented

The command plot() allows for many options, to control the number of coordinate lines to be drawn, their style and color, as well as the coordinate ranges:

graph = Y.plot(X, ranges={r:(1,2), th:(0,pi/2)}, nb_values=4, color={r:'blue', th:'green', ph:'red'})
show(graph, aspect_ratio=1)

3D rendering not yet implemented

Conversly, the chart $X|_{U}$ can be plotted in terms of the chart $Y$ (this is not possible for the whole chart $X$ since its domain is larger than that of chart $Y$):

X_U.plot(Y)

3D rendering not yet implemented

Points on the manifold

A point on $\mathcal{M}$ is defined by its coordinates in a given chart:

p = M.point((1,2,-1), X, name='p') ; print p ; p

point 'p' on 3-dimensional manifold 'M'

$p$

Since $X=(\mathcal{M}, (x,y,z))$ is the manifold's default chart, its name can be omitted:

p = M.point((1,2,-1), name='p') ; print p ; p

point 'p' on 3-dimensional manifold 'M'

$p$

Of course, $p$ belongs to $\mathcal{M}$:

p in M

$\mathrm{True}$

It is also in $U$:

p in U

$\mathrm{True}$

Indeed the coordinates of $p$ have $y\not=0$:

p.coord(X)

($1$, $2$, $-1$)

Note in passing that since $X$ is the default chart on $\mathcal{M}$, its name can be omitted in the arguments of coord():

p.coord()

($1$, $2$, $-1$)

The coordinates of $p$ can also be obtained by letting the chart acting of the point (from the very definition of a chart!):

X(p)

($1$, $2$, $-1$)

Let $q$ be a point with $y = 0$ and $x \geq 0$:

q = M.point((1,0,2), name='q')

This time, the point does not belong to $U$:

q in U

$\mathrm{False}$

Accordingly, we cannot ask for the coordinates of $q$ in the chart $Y=(U, (r,\theta,\phi))$:

q.coord(Y)

Error in lines 1-1 Traceback (most recent call last): File "/projects/sage/sage-6.9/local/lib/python2.7/site-packages/smc_sagews/sage_server.py", line 905, in execute exec compile(block+'\n', '', 'single') in namespace, locals File "", line 1, in <module> File "/projects/sage/sage-6.9/local/lib/python2.7/site-packages/sage/geometry/manifolds/point.py", line 341, in coord "of " + str(chart)) ValueError: The point does not belong to the domain of chart (U, (r, th, ph))

but we can for point $p$:

p.coord(Y)

($\sqrt{3} \sqrt{2}$, $\pi - \arctan\left(\sqrt{5}\right)$, $\arctan\left(2\right)$)

Y(p)

($\sqrt{3} \sqrt{2}$, $\pi - \arctan\left(\sqrt{5}\right)$, $\arctan\left(2\right)$)

Points can be compared:

q == p

$\mathrm{False}$

p1 = U.point((sqrt(6), pi-atan(sqrt(5)), atan(2)), Y)
p1 == p

$\mathrm{True}$

In Sage's terminology, points are elements, whose parents are the manifold on which they have been defined:

p.parent()

$\mathcal{M}$

q.parent()

$\mathcal{M}$

p1.parent()

$\mathcal{M}$

Scalar fields

A scalar field is a differentiable mapping $U\subset \mathcal{M} \longrightarrow \mathbb{R}$, where $U$ is an open subset of $\mathcal{M}$.

The scalar field is defined by its expressions in terms of charts covering its domain (in general more than one chart is necessary to cover all the domain):

f = U.scalar_field({X_U: x+y^2+z^3}, name='f') ; print f

scalar field 'f' on the open subset 'U' of the 3-dimensional manifold 'M'

The coordinate expressions of the scalar field are passed as a Python dictionary, with the charts as keys, hence the writing {X_U: x+y^2+z^3}.

Since in the present case, there is only one chart in the dictionary, an alternative writing is

f = U.scalar_field(x+y^2+z^3, chart=X_U, name='f') ; print f

scalar field 'f' on the open subset 'U' of the 3-dimensional manifold 'M'

Since X_U is the domain's default chart, it can be omitted in the above declaration:

f = U.scalar_field(x+y^2+z^3, name='f') ; print f

scalar field 'f' on the open subset 'U' of the 3-dimensional manifold 'M'

As a mapping $U\subset\mathcal{M}\longrightarrow\mathbb{R}$, a scalar field acts on points, not on coordinates:

f(p)

$4$

The expression of the scalar field in terms of the coordinates $(x,y,z)$:

f.display(X_U)

$\begin{array}{llcl} f:& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & z^{3} + y^{2} + x \end{array}$

If the method display() is used without any argument, it displays the coordinate expression of the scalar field in all the charts defined on the domain (except for subcharts, i.e. the restrictions of some chart to a subdomain):

f.display()

$\begin{array}{llcl} f:& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & z^{3} + y^{2} + x \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right) \end{array}$

Note that the expression of the scalar field in terms of the coordinates $(r,\theta,\phi)$ has not been provided by the user: it has been automatically computed via the change-of-coordinate formula declared above in the transition map.

f.display(Y)

$\begin{array}{llcl} f:& U & \longrightarrow & \mathbb{R} \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right) \end{array}$

In each chart, the scalar field is represented by a function of the chart coordinates (an object of the type FunctionChart described above), which is accessible via the method function_chart():

f.function_chart(X_U)

$z^{3} + y^{2} + x$

f.function_chart(X_U).display()

$\left(x, y, z\right) \mapsto z^{3} + y^{2} + x$

f.function_chart(Y)

$r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right)$

f.function_chart(Y).display()

$\left(r, {\theta}, {\phi}\right) \mapsto r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right)$

The "raw" symbolic expression is returned by the method expr():

f.expr(X_U)

$z^{3} + y^{2} + x$

f.expr(Y)

$r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right)$

f.expr(Y) is f.function_chart(Y).expr()

$\mathrm{True}$

A scalar field can also be defined by some unspecified function of the coordinates:

h = U.scalar_field(function('H', x, y, z), name='h') ; print h

scalar field 'h' on the open subset 'U' of the 3-dimensional manifold 'M'

h.display()

$\begin{array}{llcl} h:& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & H\left(x, y, z\right) \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & H\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) \end{array}$

h.display(Y)

$\begin{array}{llcl} h:& U & \longrightarrow & \mathbb{R} \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & H\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) \end{array}$

h(p) # remember that p is the point of coordinates (1,2,-1) in the chart X_U

$H\left(1, 2, -1\right)$

The parent of $f$ is the set $C^\infty(U)$ of all smooth scalar fields on $U$, which is a commutative algebra over $\mathbb{R}$:

CU = f.parent() ; CU

$C^\infty(U)$

print CU

algebra of scalar fields on the open subset 'U' of the 3-dimensional manifold 'M'

CU.category()

$\mathbf{CommutativeAlgebras}_{\text{SR}}$

 

The base ring of the algebra is the field $\mathbb{R}$, which is represented by Sage's Symbolic Ring (SR):

 

CU.base_ring()

$\text{SR}$

Arithmetic operations on scalar fields are defined through the algebra structure:

s = f + 2*h ; print s

scalar field on the open subset 'U' of the 3-dimensional manifold 'M'

s.display()

$\begin{array}{llcl} & U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & z^{3} + y^{2} + x + 2 \, H\left(x, y, z\right) \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right) + 2 \, H\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) \end{array}$

Tangent spaces

The tangent vector space to the manifold at point $p$ is obtained as follows:

Tp = p.tangent_space() ; Tp

$T_{p}\,\mathcal{M}$

print Tp

tangent space at point 'p' on 3-dimensional manifold 'M'

$T_p\, \mathcal{M}$ is a 2-dimensional vector space over $\mathbb{R}$ (represented here by Sage Symbolic Ring (SR)) :

Tp.category()

$\mathbf{VectorSpaces}_{\text{SR}}$

Tp.dim()

$3$

$T_p\, \mathcal{M}$ is automatically endowed with vector bases deduced from the vector frames defined around the point:

Tp.bases()

[$\left(\frac{\partial}{\partial x },\frac{\partial}{\partial y },\frac{\partial}{\partial z }\right)$, $\left(\frac{\partial}{\partial r },\frac{\partial}{\partial {\theta} },\frac{\partial}{\partial {\phi} }\right)$]

For the tangent space at the point $q$, on the contrary, there is only one pre-defined basis, since $q$ is not in the domain $U$ of the frame associated with coordinates $(r,\theta,\phi)$:

Tq = q.tangent_space()
Tq.bases()

[$\left(\frac{\partial}{\partial x },\frac{\partial}{\partial y },\frac{\partial}{\partial z }\right)$]

A random element:

v = Tp.an_element() ; print v

tangent vector at point 'p' on 3-dimensional manifold 'M'

v.display()

$\frac{\partial}{\partial x } + 2 \frac{\partial}{\partial y } + 3 \frac{\partial}{\partial z }$

u = Tq.an_element() ; print u

tangent vector at point 'q' on 3-dimensional manifold 'M'

u.display()

$\frac{\partial}{\partial x } + 2 \frac{\partial}{\partial y } + 3 \frac{\partial}{\partial z }$

Note that, despite what the above simplified writing may suggest (the mention of the point $p$ or $q$ is omitted in the basis vectors), $u$ and $v$ are different vectors, for they belong to different vector spaces:

v.parent()

$T_{p}\,\mathcal{M}$

u.parent()

$T_{q}\,\mathcal{M}$

In particular, it is not possible to add $u$ and $v$:

s = u + v

Error in lines 1-1 Traceback (most recent call last): File "/projects/sage/sage-6.9/local/lib/python2.7/site-packages/smc_sagews/sage_server.py", line 905, in execute exec compile(block+'\n', '', 'single') in namespace, locals File "", line 1, in <module> File "sage/structure/element.pyx", line 1365, in sage.structure.element.ModuleElement.__add__ (/projects/sage/sage-6.9/src/build/cythonized/sage/structure/element.c:11960) return coercion_model.bin_op(left, right, add) File "sage/structure/coerce.pyx", line 1070, in sage.structure.coerce.CoercionModel_cache_maps.bin_op (/projects/sage/sage-6.9/src/build/cythonized/sage/structure/coerce.c:9739) raise TypeError(arith_error_message(x,y,op)) TypeError: unsupported operand parent(s) for '+': 'tangent space at point 'q' on 3-dimensional manifold 'M'' and 'tangent space at point 'p' on 3-dimensional manifold 'M''

Vector Fields

Each chart defines a vector frame on the chart domain: the so-called coordinate basis:

X.frame()

$\left(\mathcal{M} ,\left(\frac{\partial}{\partial x },\frac{\partial}{\partial y },\frac{\partial}{\partial z }\right)\right)$

X.frame().domain()  # this frame is defined on the whole manifold

$\mathcal{M}$

Y.frame()

$\left(U ,\left(\frac{\partial}{\partial r },\frac{\partial}{\partial {\theta} },\frac{\partial}{\partial {\phi} }\right)\right)$

Y.frame().domain() # this frame is defined only on U

$U$

The list of frames defined on a given open subset is returned by the method frames():

M.frames()

[$\left(\mathcal{M} ,\left(\frac{\partial}{\partial x },\frac{\partial}{\partial y },\frac{\partial}{\partial z }\right)\right)$, $\left(U ,\left(\frac{\partial}{\partial x },\frac{\partial}{\partial y },\frac{\partial}{\partial z }\right)\right)$, $\left(U ,\left(\frac{\partial}{\partial r },\frac{\partial}{\partial {\theta} },\frac{\partial}{\partial {\phi} }\right)\right)$]

U.frames()

[$\left(U ,\left(\frac{\partial}{\partial x },\frac{\partial}{\partial y },\frac{\partial}{\partial z }\right)\right)$, $\left(U ,\left(\frac{\partial}{\partial r },\frac{\partial}{\partial {\theta} },\frac{\partial}{\partial {\phi} }\right)\right)$]

M.default_frame()

$\left(\mathcal{M} ,\left(\frac{\partial}{\partial x },\frac{\partial}{\partial y },\frac{\partial}{\partial z }\right)\right)$

Unless otherwise specified (via the command set_default_frame()), the default frame is that associated with the default chart:

M.default_frame() is M.default_chart().frame()

$\mathrm{True}$

U.default_frame() is U.default_chart().frame()

$\mathrm{True}$

Individual elements of a frame can be accessed by means of their indices:

e = U.default_frame() ; e2 = e[2] ; e2

$\frac{\partial}{\partial y }$

print e2

vector field 'd/dy' on the open subset 'U' of the 3-dimensional manifold 'M'

We may define a new vector field as follows:

v = e[2] + 2*x*e[3] ; print v

vector field on the open subset 'U' of the 3-dimensional manifold 'M'

v.display()

$\frac{\partial}{\partial y } + 2 \, x \frac{\partial}{\partial z }$

A vector field can be defined by its components with respect to a given vector frame. When the latter is not specified, the open set's default frame is of course assumed:

v = U.vector_field(name='v') # vector field defined on the open set U
v[1] = 1+y
v[2] = -x
v[3] = x*y*z
v.display()

$v = \left( y + 1 \right) \frac{\partial}{\partial x } -x \frac{\partial}{\partial y } + x y z \frac{\partial}{\partial z }$

Vector fields on $U$ are Sage element objects, whose parent is the set $\mathcal{X}(U)$ of vector fields defined on $U$:

v.parent()

$\mathcal{X}\left(U\right)$

The set $\mathcal{X}(U)$ is a module over the commutative algebra $C^\infty(U)$ of scalar fields on $U$:

print v.parent()

free module X(U) of vector fields on the open subset 'U' of the 3-dimensional manifold 'M'

print v.parent().category()

Category of modules over algebra of scalar fields on the open subset 'U' of the 3-dimensional manifold 'M'

v.parent().base_ring()

$C^\infty(U)$

A vector field acts on scalar fields:

f.display()

$\begin{array}{llcl} f:& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & z^{3} + y^{2} + x \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right) \end{array}$

s = v(f) ; print s

scalar field 'v(f)' on the open subset 'U' of the 3-dimensional manifold 'M'

s.display()

$\begin{array}{llcl} v\left(f\right):& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & 3 \, x y z^{3} - {\left(2 \, x - 1\right)} y + 1 \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & -3 \, r^{5} \cos\left({\phi}\right) \cos\left({\theta}\right)^{5} \sin\left({\phi}\right) + 3 \, r^{5} \cos\left({\phi}\right) \cos\left({\theta}\right)^{3} \sin\left({\phi}\right) - 2 \, r^{2} \cos\left({\phi}\right) \sin\left({\phi}\right) \sin\left({\theta}\right)^{2} + r \sin\left({\phi}\right) \sin\left({\theta}\right) + 1 \end{array}$

e[3].display()

$\frac{\partial}{\partial z } = \frac{\partial}{\partial z }$

e[3](f).display()

$\begin{array}{llcl} \frac{\partial}{\partial z } \left( f \right) : & U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & 3 \, z^{2} \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & 3 \, r^{2} \cos\left({\theta}\right)^{2} \end{array}$

Unset components are assumed to be zero:

w = U.vector_field(name='w')
w[2] = 3
w.display()

$w = 3 \frac{\partial}{\partial y }$

A vector field on $U$ can be expanded in the vector frame associated with the chart $(r,\theta,\phi)$:

v.display(Y.frame())

$v = \left( \frac{x y z^{2} + x}{\sqrt{x^{2} + y^{2} + z^{2}}} \right) \frac{\partial}{\partial r } + \left( -\frac{{\left(x^{3} y + x y^{3} - x\right)} \sqrt{x^{2} + y^{2}} z}{x^{4} + 2 \, x^{2} y^{2} + y^{4} + {\left(x^{2} + y^{2}\right)} z^{2}} \right) \frac{\partial}{\partial {\theta} } + \left( -\frac{x^{2} + y^{2} + y}{x^{2} + y^{2}} \right) \frac{\partial}{\partial {\phi} }$

By default, the components are expressed in terms of the default coordinates $(x,y,z)$. To express them in terms of the coordinates $(r,\theta,\phi)$, one should add the corresponding chart as the second argument of the method display():

v.display(Y.frame(), Y)

$v = \left( r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) \sin\left({\theta}\right)^{2} + \cos\left({\phi}\right) \sin\left({\theta}\right) \right) \frac{\partial}{\partial r } + \left( -\frac{r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) \sin\left({\theta}\right)^{3} - \cos\left({\phi}\right) \cos\left({\theta}\right)}{r} \right) \frac{\partial}{\partial {\theta} } + \left( -\frac{r \sin\left({\theta}\right) + \sin\left({\phi}\right)}{r \sin\left({\theta}\right)} \right) \frac{\partial}{\partial {\phi} }$

for i in M.irange(): e[i].display(Y.frame(), Y)

$\frac{\partial}{\partial x } = \cos\left({\phi}\right) \sin\left({\theta}\right) \frac{\partial}{\partial r } + \frac{\cos\left({\phi}\right) \cos\left({\theta}\right)}{r} \frac{\partial}{\partial {\theta} } -\frac{\sin\left({\phi}\right)}{r \sin\left({\theta}\right)} \frac{\partial}{\partial {\phi} }$

$\frac{\partial}{\partial y } = \sin\left({\phi}\right) \sin\left({\theta}\right) \frac{\partial}{\partial r } + \frac{\cos\left({\theta}\right) \sin\left({\phi}\right)}{r} \frac{\partial}{\partial {\theta} } + \frac{\cos\left({\phi}\right)}{r \sin\left({\theta}\right)} \frac{\partial}{\partial {\phi} }$

$\frac{\partial}{\partial z } = \cos\left({\theta}\right) \frac{\partial}{\partial r } -\frac{\sin\left({\theta}\right)}{r} \frac{\partial}{\partial {\theta} }$

The components of a tensor field w.r.t. the default frame can also be obtained as a list, via the command [:]:

v[:]

[$y + 1$, $-x$, $x y z$]

An alternative is to use the method display_comp():

v.display_comp()

$\begin{array}{lcl} v_{ \phantom{\, x } }^{ \, x } & = & y + 1 \\ v_{ \phantom{\, y } }^{ \, y } & = & -x \\ v_{ \phantom{\, z } }^{ \, z } & = & x y z \end{array}$

To obtain the components w.r.t. to another frame, one may go through the method comp() and specify the frame:

v.comp(Y.frame())[:]

[$\frac{x y z^{2} + x}{\sqrt{x^{2} + y^{2} + z^{2}}}$, $-\frac{{\left(x^{3} y + x y^{3} - x\right)} \sqrt{x^{2} + y^{2}} z}{x^{4} + 2 \, x^{2} y^{2} + y^{4} + {\left(x^{2} + y^{2}\right)} z^{2}}$, $-\frac{x^{2} + y^{2} + y}{x^{2} + y^{2}}$]

However a shortcut is to provide the frame as the first argument of the square brackets:

v[Y.frame(), :]

[$\frac{x y z^{2} + x}{\sqrt{x^{2} + y^{2} + z^{2}}}$, $-\frac{{\left(x^{3} y + x y^{3} - x\right)} \sqrt{x^{2} + y^{2}} z}{x^{4} + 2 \, x^{2} y^{2} + y^{4} + {\left(x^{2} + y^{2}\right)} z^{2}}$, $-\frac{x^{2} + y^{2} + y}{x^{2} + y^{2}}$]

v.display_comp(Y.frame())

$\begin{array}{lcl} v_{ \phantom{\, r } }^{ \, r } & = & \frac{x y z^{2} + x}{\sqrt{x^{2} + y^{2} + z^{2}}} \\ v_{ \phantom{\, {\theta} } }^{ \, {\theta} } & = & -\frac{{\left(x^{3} y + x y^{3} - x\right)} \sqrt{x^{2} + y^{2}} z}{x^{4} + 2 \, x^{2} y^{2} + y^{4} + {\left(x^{2} + y^{2}\right)} z^{2}} \\ v_{ \phantom{\, {\phi} } }^{ \, {\phi} } & = & -\frac{x^{2} + y^{2} + y}{x^{2} + y^{2}} \end{array}$

Components are shown expressed in terms of the default's coordinates; to get them in terms of the coordinates $(r,\theta,\phi)$ instead, add the chart name as the last argument in the square brackets:

v[Y.frame(), :, Y]

[$r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) \sin\left({\theta}\right)^{2} + \cos\left({\phi}\right) \sin\left({\theta}\right)$, $-\frac{r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) \sin\left({\theta}\right)^{3} - \cos\left({\phi}\right) \cos\left({\theta}\right)}{r}$, $-\frac{r \sin\left({\theta}\right) + \sin\left({\phi}\right)}{r \sin\left({\theta}\right)}$]

or specify the chart in display_comp():

v.display_comp(Y.frame(), chart=Y)

$\begin{array}{lcl} v_{ \phantom{\, r } }^{ \, r } & = & r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) \sin\left({\theta}\right)^{2} + \cos\left({\phi}\right) \sin\left({\theta}\right) \\ v_{ \phantom{\, {\theta} } }^{ \, {\theta} } & = & -\frac{r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) \sin\left({\theta}\right)^{3} - \cos\left({\phi}\right) \cos\left({\theta}\right)}{r} \\ v_{ \phantom{\, {\phi} } }^{ \, {\phi} } & = & -\frac{r \sin\left({\theta}\right) + \sin\left({\phi}\right)}{r \sin\left({\theta}\right)} \end{array}$

To get some components of a vector as a scalar field, instead of a coordinate expression, use double square brackets:

print v[[1]]

scalar field on the open subset 'U' of the 3-dimensional manifold 'M'

v[[1]].display()

$\begin{array}{llcl} & U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & y + 1 \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r \sin\left({\phi}\right) \sin\left({\theta}\right) + 1 \end{array}$

v[[1]].expr(X_U)

$y + 1$

A vector field can be defined with components being unspecified functions of the coordinates:

u = U.vector_field(name='u')
u[:] = [function('u_x', x,y,z), function('u_y', x,y,z), function('u_z', x,y,z)]
u.display()

$u = u_{x}\left(x, y, z\right) \frac{\partial}{\partial x } + u_{y}\left(x, y, z\right) \frac{\partial}{\partial y } + u_{z}\left(x, y, z\right) \frac{\partial}{\partial z }$

s = v + u ; s.set_name('s') ; s.display()

$s = \left( y + u_{x}\left(x, y, z\right) + 1 \right) \frac{\partial}{\partial x } + \left( -x + u_{y}\left(x, y, z\right) \right) \frac{\partial}{\partial y } + \left( x y z + u_{z}\left(x, y, z\right) \right) \frac{\partial}{\partial z }$

Values of vector fields at a given point

The value of a vector field at some point of the manifold is obtained via the method at():

vp = v.at(p) ; print vp

tangent vector v at point 'p' on 3-dimensional manifold 'M'

vp.display()

$v = 3 \frac{\partial}{\partial x } -\frac{\partial}{\partial y } -2 \frac{\partial}{\partial z }$

Indeed, recall that, w.r.t. chart X_U=$(x,y,z)$,  the coordinates of the point $p$ and the components of the vector field $v$ are

p.coord(X_U)

($1$, $2$, $-1$)

v.display(X_U.frame(), X_U)

$v = \left( y + 1 \right) \frac{\partial}{\partial x } -x \frac{\partial}{\partial y } + x y z \frac{\partial}{\partial z }$

Note that to simplify the writing, the symbol used to denote the value of the vector field at point $p$ is the same as that of the vector field itself (namely $v$); this can be changed by the method set_name():

vp.set_name(latex_name='v|_p')
vp.display()

$v|_p = 3 \frac{\partial}{\partial x } -\frac{\partial}{\partial y } -2 \frac{\partial}{\partial z }$

Of course, $v|_p$ belongs to the tangent space at $p$:

vp.parent()

$T_{p}\,\mathcal{M}$

vp in p.tangent_space()

$\mathrm{True}$

up = u.at(p) ; print up

tangent vector u at point 'p' on 3-dimensional manifold 'M'

up.display()

$u = u_{x}\left(1, 2, -1\right) \frac{\partial}{\partial x } + u_{y}\left(1, 2, -1\right) \frac{\partial}{\partial y } + u_{z}\left(1, 2, -1\right) \frac{\partial}{\partial z }$

1-forms

A 1-form on $\mathcal{M}$ is a field of linear forms. For instance, it can be the differential of a scalar field:

df = f.differential() ; print df

1-form 'df' on the open subset 'U' of the 3-dimensional manifold 'M'

df.display()

$\mathrm{d}f = \mathrm{d} x + 2 \, y \mathrm{d} y + 3 \, z^{2} \mathrm{d} z$

In the above writing, the 1-form is expanded over the basis $(\mathrm{d}x, \mathrm{d}y, \mathrm{d}z)$ associated with the chart $(x,y,z)$. This basis can be accessed via the member coframe:

dX = X.coframe() ; dX

$\left(\mathcal{M} ,\left(\mathrm{d} x,\mathrm{d} y,\mathrm{d} z\right)\right)$

The list of all coframes defined on a given manifold open subset is returned by the method coframes():

M.coframes()

[$\left(\mathcal{M} ,\left(\mathrm{d} x,\mathrm{d} y,\mathrm{d} z\right)\right)$, $\left(U ,\left(\mathrm{d} x,\mathrm{d} y,\mathrm{d} z\right)\right)$, $\left(U ,\left(\mathrm{d} r,\mathrm{d} {\theta},\mathrm{d} {\phi}\right)\right)$]

As for a vector field, the value of the differential form at some point on the manifold is obtained by the method at():

dfp = df.at(p) ; print dfp

Linear form df on the tangent space at point 'p' on 3-dimensional manifold 'M'

dfp.display()

$\mathrm{d}f = \mathrm{d} x + 4 \mathrm{d} y + 3 \mathrm{d} z$

Recall that

p.coord()

($1$, $2$, $-1$)

The linear form $\mathrm{d}f|_p$ belongs to the dual of the tangent vector space at $p$:

dfp.parent()

$T_{p}\,\mathcal{M}^*$

dfp.parent() is p.tangent_space().dual()

$\mathrm{True}$

As such, it is acting on vectors at $p$, yielding a real number:

print vp ; vp.display()

tangent vector v at point 'p' on 3-dimensional manifold 'M'

$v|_p = 3 \frac{\partial}{\partial x } -\frac{\partial}{\partial y } -2 \frac{\partial}{\partial z }$

dfp(vp)

$-7$

print up ; up.display()

tangent vector u at point 'p' on 3-dimensional manifold 'M'

$u = u_{x}\left(1, 2, -1\right) \frac{\partial}{\partial x } + u_{y}\left(1, 2, -1\right) \frac{\partial}{\partial y } + u_{z}\left(1, 2, -1\right) \frac{\partial}{\partial z }$

dfp(up)

$u_{x}\left(1, 2, -1\right) + 4 \, u_{y}\left(1, 2, -1\right) + 3 \, u_{z}\left(1, 2, -1\right)$

The differential 1-form of the unspecified scalar field $h$:

h.display() ; dh = h.differential() ; dh.display()

$\begin{array}{llcl} h:& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & H\left(x, y, z\right) \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & H\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) \end{array}$

$\mathrm{d}h = \frac{\partial\,H}{\partial x} \mathrm{d} x + \frac{\partial\,H}{\partial y} \mathrm{d} y + \frac{\partial\,H}{\partial z} \mathrm{d} z$

A 1-form can also be defined from scratch:

om = U.one_form('omega', r'\omega') ; print om

1-form 'omega' on the open subset 'U' of the 3-dimensional manifold 'M'

It can be specified by providing its components in a given coframe:

om[:] = [x^2+y^2, z, x-z]    # components in the default coframe (dx,dy,dz)
om.display()

$\omega = \left( x^{2} + y^{2} \right) \mathrm{d} x + z \mathrm{d} y + \left( x - z \right) \mathrm{d} z$

Of course, one may set the components in a frame different from the default one:

om[Y.frame(), :, Y] = [r*sin(th)*cos(ph), 0, r*sin(th)*sin(ph)]
om.display(Y.frame(), Y)

$\omega = r \cos\left({\phi}\right) \sin\left({\theta}\right) \mathrm{d} r + r \sin\left({\phi}\right) \sin\left({\theta}\right) \mathrm{d} {\phi}$

The components in the coframe $(\mathrm{d}x,\mathrm{d}y,\mathrm{d}z)$ are updated automatically:

om.display()

$\omega = \left( \frac{x^{4} + x^{2} y^{2} - \sqrt{x^{2} + y^{2} + z^{2}} y^{2}}{\sqrt{x^{2} + y^{2} + z^{2}} {\left(x^{2} + y^{2}\right)}} \right) \mathrm{d} x + \left( \frac{x^{3} y + x y^{3} + \sqrt{x^{2} + y^{2} + z^{2}} x y}{\sqrt{x^{2} + y^{2} + z^{2}} {\left(x^{2} + y^{2}\right)}} \right) \mathrm{d} y + \left( \frac{x z}{\sqrt{x^{2} + y^{2} + z^{2}}} \right) \mathrm{d} z$

Let us revert to the values set previously:

om[:] = [x^2+y^2, z, x-z]
om.display()

$\omega = \left( x^{2} + y^{2} \right) \mathrm{d} x + z \mathrm{d} y + \left( x - z \right) \mathrm{d} z$

This time, the components in the coframe $(\mathrm{d}r, \mathrm{d}\theta,\mathrm{d}\phi)$ are those that are updated:

om.display(Y.frame(), Y)

$\omega = \left( r^{2} \cos\left({\phi}\right) \sin\left({\theta}\right)^{3} + r {\left(\cos\left({\phi}\right) + \sin\left({\phi}\right)\right)} \cos\left({\theta}\right) \sin\left({\theta}\right) - r \cos\left({\theta}\right)^{2} \right) \mathrm{d} r + \left( r^{2} \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) + r^{2} \cos\left({\theta}\right) \sin\left({\theta}\right) + {\left(r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right) - r^{2} \cos\left({\phi}\right)\right)} \sin\left({\theta}\right)^{2} \right) \mathrm{d} {\theta} + \left( -r^{3} \sin\left({\phi}\right) \sin\left({\theta}\right)^{3} + r^{2} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\theta}\right) \right) \mathrm{d} {\phi}$

A 1-form acts on vector fields, resulting in a scalar field:

v.display() ; om.display() ; print om(v) ; om(v).display()

$v = \left( y + 1 \right) \frac{\partial}{\partial x } -x \frac{\partial}{\partial y } + x y z \frac{\partial}{\partial z }$

$\omega = \left( x^{2} + y^{2} \right) \mathrm{d} x + z \mathrm{d} y + \left( x - z \right) \mathrm{d} z$

scalar field 'omega(v)' on the open subset 'U' of the 3-dimensional manifold 'M'

$\begin{array}{llcl} \omega\left(v\right):& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & -x y z^{2} + x^{2} y + y^{3} + x^{2} + y^{2} + {\left(x^{2} y - x\right)} z \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & -r^{2} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\theta}\right) + {\left(r^{4} \cos\left({\phi}\right)^{2} \cos\left({\theta}\right) \sin\left({\phi}\right) + r^{3} \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{3} - {\left(r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) - r^{2}\right)} \sin\left({\theta}\right)^{2} \end{array}$

df.display() ; print df(v) ; df(v).display()

$\mathrm{d}f = \mathrm{d} x + 2 \, y \mathrm{d} y + 3 \, z^{2} \mathrm{d} z$

scalar field 'df(v)' on the open subset 'U' of the 3-dimensional manifold 'M'

$\begin{array}{llcl} \mathrm{d}f\left(v\right):& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & 3 \, x y z^{3} - {\left(2 \, x - 1\right)} y + 1 \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r \sin\left({\phi}\right) \sin\left({\theta}\right) + {\left(3 \, r^{5} \cos\left({\phi}\right) \cos\left({\theta}\right)^{3} \sin\left({\phi}\right) - 2 \, r^{2} \cos\left({\phi}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{2} + 1 \end{array}$

u.display() ; om(u).display()

$u = u_{x}\left(x, y, z\right) \frac{\partial}{\partial x } + u_{y}\left(x, y, z\right) \frac{\partial}{\partial y } + u_{z}\left(x, y, z\right) \frac{\partial}{\partial z }$

$\begin{array}{llcl} \omega\left(u\right):& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & x^{2} u_{x}\left(x, y, z\right) + y^{2} u_{x}\left(x, y, z\right) + z {\left(u_{y}\left(x, y, z\right) - u_{z}\left(x, y, z\right)\right)} + x u_{z}\left(x, y, z\right) \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r^{2} \sin\left({\theta}\right)^{2} u_{x}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) + r \cos\left({\theta}\right) u_{y}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) + {\left(r \cos\left({\phi}\right) \sin\left({\theta}\right) - r \cos\left({\theta}\right)\right)} u_{z}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) \end{array}$

In the case of a differential 1-form, the following identity holds:

df(v) == v(f)

$\mathrm{True}$

1-forms are Sage element objects, whose parent is the set $\mathcal{T}^{(0,1)}(U)$ of all tensor fields of type (0,1) defined on $U$:

df.parent()

$\Lambda^{1}\left(U\right)$

print df.parent()

Free module /\^1(U) of 1-forms on the open subset 'U' of the 3-dimensional manifold 'M'

print om.parent()

Free module /\^1(U) of 1-forms on the open subset 'U' of the 3-dimensional manifold 'M'

$\mathcal{T}^{(0,1)}(U)$ is actually the dual of the free module $\mathcal{X}(U)$:

df.parent() is v.parent().dual()

$\mathrm{True}$

Differential forms and exterior calculus

The exterior product of two 1-forms is taken via the method wedge() and results in a 2-form:

a = om.wedge(df) ; print a ; a.display()

2-form 'omega/\df' on the open subset 'U' of the 3-dimensional manifold 'M'

$\omega\wedge \mathrm{d}f = \left( 2 \, x^{2} y + 2 \, y^{3} - z \right) \mathrm{d} x\wedge \mathrm{d} y + \left( 3 \, {\left(x^{2} + y^{2}\right)} z^{2} - x + z \right) \mathrm{d} x\wedge \mathrm{d} z + \left( 3 \, z^{3} - 2 \, x y + 2 \, y z \right) \mathrm{d} y\wedge \mathrm{d} z$

A matrix view of the components:

a[:]

$\left(\begin{array}{rrr} 0 & 2 \, x^{2} y + 2 \, y^{3} - z & 3 \, {\left(x^{2} + y^{2}\right)} z^{2} - x + z \\ -2 \, x^{2} y - 2 \, y^{3} + z & 0 & 3 \, z^{3} - 2 \, x y + 2 \, y z \\ -3 \, {\left(x^{2} + y^{2}\right)} z^{2} + x - z & -3 \, z^{3} + 2 \, x y - 2 \, y z & 0 \end{array}\right)$

Displaying only the non-vanishing components, skipping the redundant ones (i.e. those that can be deduced by antisymmetry):

a.display_comp(only_nonredundant=True)

$\begin{array}{lcl} \omega\wedge \mathrm{d}f_{ \, x \, y }^{ \phantom{\, x } \phantom{\, y } } & = & 2 \, x^{2} y + 2 \, y^{3} - z \\ \omega\wedge \mathrm{d}f_{ \, x \, z }^{ \phantom{\, x } \phantom{\, z } } & = & 3 \, {\left(x^{2} + y^{2}\right)} z^{2} - x + z \\ \omega\wedge \mathrm{d}f_{ \, y \, z }^{ \phantom{\, y } \phantom{\, z } } & = & 3 \, z^{3} - 2 \, x y + 2 \, y z \end{array}$

The 2-form $\omega\wedge\mathrm{d}f$ can be expanded on the $(\mathrm{d}r,\mathrm{d}\theta,\mathrm{d}\phi)$ coframe:

a.display(Y.frame(), Y)

$\omega\wedge \mathrm{d}f = \left( 3 \, r^{5} \cos\left({\phi}\right) \sin\left({\theta}\right)^{4} - {\left(3 \, r^{5} \cos\left({\phi}\right) - 3 \, r^{4} \cos\left({\theta}\right) \sin\left({\phi}\right) - 2 \, r^{3} \cos\left({\phi}\right) \sin\left({\phi}\right)^{2}\right)} \sin\left({\theta}\right)^{2} - {\left(3 \, r^{4} \sin\left({\phi}\right) + r^{2} \cos\left({\phi}\right)\right)} \cos\left({\theta}\right) - {\left(2 \, r^{3} \cos\left({\theta}\right) \sin\left({\phi}\right)^{2} + {\left(\sin\left({\phi}\right)^{2} - 1\right)} r^{2}\right)} \sin\left({\theta}\right) \right) \mathrm{d} r\wedge \mathrm{d} {\theta} + \left( 2 \, r^{4} \sin\left({\phi}\right) \sin\left({\theta}\right)^{5} + {\left(3 \, r^{5} \cos\left({\theta}\right)^{3} \sin\left({\phi}\right) + 2 \, r^{3} \cos\left({\phi}\right)^{2} \cos\left({\theta}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{3} - {\left(2 \, r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) + {\left(\cos\left({\phi}\right) \sin\left({\phi}\right) + 1\right)} r^{2} \cos\left({\theta}\right)\right)} \sin\left({\theta}\right)^{2} - {\left(3 \, r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right)^{4} - r^{2} \cos\left({\theta}\right)^{2} \sin\left({\phi}\right)\right)} \sin\left({\theta}\right) \right) \mathrm{d} r\wedge \mathrm{d} {\phi} + \left( -r^{3} \cos\left({\theta}\right)^{2} \sin\left({\theta}\right) - {\left(3 \, r^{6} \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) + 2 \, r^{4} \cos\left({\phi}\right)^{2} \sin\left({\phi}\right) - 2 \, r^{5} \cos\left({\theta}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{4} + {\left(2 \, r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) + r^{3} \cos\left({\phi}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{3} + {\left(3 \, r^{5} \cos\left({\phi}\right) \cos\left({\theta}\right)^{3} - r^{3} \cos\left({\theta}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{2} \right) \mathrm{d} {\theta}\wedge \mathrm{d} {\phi}$

As a 2-form, $A:=\omega\wedge\mathrm{d}f$ can be applied to a pair of vectors and is antisymmetric:

a.set_name('A')
print a(u,v) ; a(u,v).display()

scalar field 'A(u,v)' on the open subset 'U' of the 3-dimensional manifold 'M'

$\begin{array}{llcl} A\left(u,v\right):& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & 3 \, x y z^{4} u_{y}\left(x, y, z\right) - 2 \, x^{2} y^{2} u_{y}\left(x, y, z\right) - 2 \, y^{4} u_{y}\left(x, y, z\right) - 2 \, {\left(x u_{x}\left(x, y, z\right) + u_{y}\left(x, y, z\right)\right)} y^{3} + 3 \, {\left(x^{3} y u_{x}\left(x, y, z\right) + x y^{3} u_{x}\left(x, y, z\right) + x u_{z}\left(x, y, z\right)\right)} z^{3} - {\left(3 \, y^{3} u_{z}\left(x, y, z\right) - {\left(2 \, x u_{y}\left(x, y, z\right) - 3 \, u_{z}\left(x, y, z\right)\right)} y^{2} + 3 \, x^{2} u_{z}\left(x, y, z\right) + {\left(3 \, x^{2} u_{z}\left(x, y, z\right) - x u_{x}\left(x, y, z\right)\right)} y\right)} z^{2} - {\left(2 \, x^{3} u_{x}\left(x, y, z\right) + 2 \, x^{2} u_{y}\left(x, y, z\right) + {\left(2 \, x^{2} - x\right)} u_{z}\left(x, y, z\right)\right)} y - {\left(2 \, x^{2} y^{2} u_{y}\left(x, y, z\right) + {\left(x^{2} u_{x}\left(x, y, z\right) - {\left(2 \, x - 1\right)} u_{z}\left(x, y, z\right) - u_{y}\left(x, y, z\right)\right)} y - x u_{x}\left(x, y, z\right) - u_{y}\left(x, y, z\right) + u_{z}\left(x, y, z\right)\right)} z + x u_{z}\left(x, y, z\right) \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & {\left(r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) \sin\left({\theta}\right)^{2} + {\left(\sin\left({\phi}\right)^{3} - \sin\left({\phi}\right)\right)} r^{4} \cos\left({\theta}\right) \sin\left({\theta}\right)^{3} + r^{2} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\theta}\right) + {\left(3 \, r^{7} \cos\left({\phi}\right) \cos\left({\theta}\right)^{3} \sin\left({\phi}\right) - 2 \, r^{4} \cos\left({\phi}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{4}\right)} u_{x}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) + {\left(3 \, r^{6} \cos\left({\phi}\right) \cos\left({\theta}\right)^{4} \sin\left({\phi}\right) \sin\left({\theta}\right)^{2} + r^{2} \cos\left({\theta}\right) \sin\left({\phi}\right) \sin\left({\theta}\right) + 2 \, {\left({\left(\sin\left({\phi}\right)^{4} - \sin\left({\phi}\right)^{2}\right)} r^{5} \cos\left({\theta}\right) - r^{4} \sin\left({\phi}\right)^{2}\right)} \sin\left({\theta}\right)^{4} + 2 \, {\left(r^{5} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right)^{2} - r^{3} \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{3} + r \cos\left({\theta}\right)\right)} u_{y}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) - {\left({\left(3 \, r^{5} \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) - 2 \, {\left(\sin\left({\phi}\right)^{3} - \sin\left({\phi}\right)\right)} r^{3}\right)} \sin\left({\theta}\right)^{3} + {\left(3 \, r^{4} \cos\left({\theta}\right)^{2} - 2 \, r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) - r^{2} \cos\left({\phi}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{2} + r \cos\left({\theta}\right) - {\left(3 \, r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right)^{3} - r^{2} \cos\left({\theta}\right) \sin\left({\phi}\right) + r \cos\left({\phi}\right)\right)} \sin\left({\theta}\right)\right)} u_{z}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) \end{array}$

a(u,v) == - a(v,u)

$\mathrm{True}$

a.symmetries()

no symmetry; antisymmetry: (0, 1)

The exterior derivative  of a differential form is taken by invoking the function xder():

dom = xder(om) ; print dom ; dom.display()

2-form 'domega' on the open subset 'U' of the 3-dimensional manifold 'M'

$\mathrm{d}\omega = -2 \, y \mathrm{d} x\wedge \mathrm{d} y +\mathrm{d} x\wedge \mathrm{d} z -\mathrm{d} y\wedge \mathrm{d} z$

da = xder(a) ; print da ; da.display()

3-form 'dA' on the open subset 'U' of the 3-dimensional manifold 'M'

$\mathrm{d}A = \left( -6 \, y z^{2} - 2 \, y - 1 \right) \mathrm{d} x\wedge \mathrm{d} y\wedge \mathrm{d} z$

The exterior derivative is nilpotent:

ddf = xder(df) ; ddf.display()

$\mathrm{d}\mathrm{d}f = 0$

ddom = xder(dom) ; ddom.display()

$\mathrm{d}\mathrm{d}\omega = 0$

Lie derivative

The Lie derivative of any tensor field with respect to a vector field is computed by the method lie_der(), with the vector field as argument:

lv_om = om.lie_der(v) ; print lv_om ; lv_om.display()

1-form on the open subset 'U' of the 3-dimensional manifold 'M'

$\left( -y z^{2} + {\left(x y - 1\right)} z + 2 \, x \right) \mathrm{d} x + \left( -x z^{2} + x^{2} + y^{2} + {\left(x^{2} + x y\right)} z \right) \mathrm{d} y + \left( -2 \, x y z + {\left(x^{2} + 1\right)} y + 1 \right) \mathrm{d} z$

lu_dh = dh.lie_der(u) ; print lu_dh ; lu_dh.display()

1-form on the open subset 'U' of the 3-dimensional manifold 'M'

$\left( u_{x}\left(x, y, z\right) \frac{\partial^2\,H}{\partial x^2} + u_{y}\left(x, y, z\right) \frac{\partial^2\,H}{\partial x\partial y} + u_{z}\left(x, y, z\right) \frac{\partial^2\,H}{\partial x\partial z} + \frac{\partial\,H}{\partial x} \frac{\partial\,u_{x}}{\partial x} + \frac{\partial\,H}{\partial y} \frac{\partial\,u_{y}}{\partial x} + \frac{\partial\,H}{\partial z} \frac{\partial\,u_{z}}{\partial x} \right) \mathrm{d} x + \left( u_{x}\left(x, y, z\right) \frac{\partial^2\,H}{\partial x\partial y} + u_{y}\left(x, y, z\right) \frac{\partial^2\,H}{\partial y^2} + u_{z}\left(x, y, z\right) \frac{\partial^2\,H}{\partial y\partial z} + \frac{\partial\,H}{\partial x} \frac{\partial\,u_{x}}{\partial y} + \frac{\partial\,H}{\partial y} \frac{\partial\,u_{y}}{\partial y} + \frac{\partial\,H}{\partial z} \frac{\partial\,u_{z}}{\partial y} \right) \mathrm{d} y + \left( u_{x}\left(x, y, z\right) \frac{\partial^2\,H}{\partial x\partial z} + u_{y}\left(x, y, z\right) \frac{\partial^2\,H}{\partial y\partial z} + u_{z}\left(x, y, z\right) \frac{\partial^2\,H}{\partial z^2} + \frac{\partial\,H}{\partial x} \frac{\partial\,u_{x}}{\partial z} + \frac{\partial\,H}{\partial y} \frac{\partial\,u_{y}}{\partial z} + \frac{\partial\,H}{\partial z} \frac{\partial\,u_{z}}{\partial z} \right) \mathrm{d} z$

Let us check Cartan identity on the 1-form $\omega$:

$\mathcal{L}_v \omega = v\cdot \mathrm{d}\omega + \mathrm{d}\langle \omega, v\rangle$

and on the 2-form $A$:

$\mathcal{L}_v A = v\cdot \mathrm{d}A + \mathrm{d}(v\cdot A)$

om.lie_der(v) == v.contract(xder(om)) + xder(om(v))

$\mathrm{True}$

a.lie_der(v) == v.contract(xder(a)) + xder(v.contract(a))

$\mathrm{True}$

The Lie derivative of a vector field along another one is the commutator of the two vectors fields:

v.lie_der(u)(f) == u(v(f)) - v(u(f))

$\mathrm{True}$

Tensor fields of arbitrary rank

Up to now, we have encountered tensor fields

• of type (0,0) (i.e. scalar fields),
• of type (1,0) (i.e. vector fields),
• of type (0,1) (i.e. 1-forms),
• of type (0,2) and antisymmetric (i.e. 2-forms).

More generally, tensor fields of any type $(p,q)$ can be introduced in SageManifolds. For instance a tensor field of type (1,2) on the open subset $U$ is declared as follows:

t = U.tensor_field(1, 2, name='T') ; print t

tensor field 'T' of type (1,2) on the open subset 'U' of the 3-dimensional manifold 'M'

As for vectors or 1-forms, the tensor's components with respect to the domain's default frame are set by means of square brackets:

t[1,2,1] = 1 + x^2
t[3,2,1] = x*y*z

Unset components are zero:

t.display()

$T = \left( x^{2} + 1 \right) \frac{\partial}{\partial x }\otimes \mathrm{d} y\otimes \mathrm{d} x + x y z \frac{\partial}{\partial z }\otimes \mathrm{d} y\otimes \mathrm{d} x$

t[:]

[[[$0$, $0$, $0$], [$x^{2} + 1$, $0$, $0$], [$0$, $0$, $0$]], [[$0$, $0$, $0$], [$0$, $0$, $0$], [$0$, $0$, $0$]], [[$0$, $0$, $0$], [$x y z$, $0$, $0$], [$0$, $0$, $0$]]]

Display of the nonzero components:

t.display_comp()

$\begin{array}{lcl} T_{ \phantom{\, x } \, y \, x }^{ \, x \phantom{\, y } \phantom{\, x } } & = & x^{2} + 1 \\ T_{ \phantom{\, z } \, y \, x }^{ \, z \phantom{\, y } \phantom{\, x } } & = & x y z \end{array}$

Double square brackets return the component (still w.r.t. the default frame) as a scalar field, while single square brackets return the expression of this scalar field in terms of the domain's default coordinates:

print t[[1,2,1]] ; t[[1,2,1]].display()

scalar field on the open subset 'U' of the 3-dimensional manifold 'M'

$\begin{array}{llcl} & U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & x^{2} + 1 \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r^{2} \cos\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + 1 \end{array}$

print t[1,2,1] ; t[1,2,1]

x^2 + 1

$x^{2} + 1$

A tensor field of type (1,2) maps a 3-tuple (1-form, vector field, vector field) to a scalar field:

print t(om, u, v) ; t(om, u, v).display()

scalar field 'T(omega,u,v)' on the open subset 'U' of the 3-dimensional manifold 'M'

$\begin{array}{llcl} T\left(\omega,u,v\right):& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & {\left(x^{2} + 1\right)} y^{3} u_{y}\left(x, y, z\right) + {\left(x^{2} + 1\right)} y^{2} u_{y}\left(x, y, z\right) - {\left(x y^{2} u_{y}\left(x, y, z\right) + x y u_{y}\left(x, y, z\right)\right)} z^{2} + {\left(x^{4} + x^{2}\right)} y u_{y}\left(x, y, z\right) + {\left(x^{2} y^{2} u_{y}\left(x, y, z\right) + x^{2} y u_{y}\left(x, y, z\right)\right)} z + {\left(x^{4} + x^{2}\right)} u_{y}\left(x, y, z\right) \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & {\left(r^{5} \cos\left({\phi}\right)^{2} \sin\left({\phi}\right) \sin\left({\theta}\right)^{5} - {\left({\left(\cos\left({\phi}\right)^{4} - \cos\left({\phi}\right)^{2}\right)} r^{5} \cos\left({\theta}\right) - r^{4} \cos\left({\phi}\right)^{2}\right)} \sin\left({\theta}\right)^{4} + {\left({\left(\cos\left({\phi}\right)^{3} - \cos\left({\phi}\right)\right)} r^{5} \cos\left({\theta}\right)^{2} + r^{4} \cos\left({\phi}\right)^{2} \cos\left({\theta}\right) \sin\left({\phi}\right) + r^{3} \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{3} - {\left(r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) - r^{2}\right)} \sin\left({\theta}\right)^{2}\right)} u_{y}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) \end{array}$

As for vectors and differential forms, the tensor components can be taken in any frame defined on the manifold:

t[Y.frame(), 1,1,1, Y]

$r^{2} \cos\left({\phi}\right)^{4} \sin\left({\phi}\right) \sin\left({\theta}\right)^{5} + {\left(\cos\left({\phi}\right)^{4} - \cos\left({\phi}\right)^{2}\right)} r^{3} \sin\left({\theta}\right)^{6} - {\left(\cos\left({\phi}\right)^{4} - \cos\left({\phi}\right)^{2}\right)} r^{3} \sin\left({\theta}\right)^{4} + \cos\left({\phi}\right)^{2} \sin\left({\phi}\right) \sin\left({\theta}\right)^{3}$

Tensor calculus

The tensor product is denoted by *:

v.tensor_type() ; a.tensor_type()

($1$, $0$)

($0$, $2$)

b = v*a ; print b ; b

tensor field 'v*A' of type (1,2) on the open subset 'U' of the 3-dimensional manifold 'M'

$v\otimes A$

The tensor product preserves the (anti)symmetries: since $A$ is a 2-form, it is antisymmetric with respect to its two arguments (positions 0 and 1); as a result, b is antisymmetric with respect to its last two arguments (positions 1 and 2):

a.symmetries()

no symmetry; antisymmetry: (0, 1)

b.symmetries()

no symmetry; antisymmetry: (1, 2)

Standard tensor arithmetics is implemented:

s = - t + 2*f* b ; print s

tensor field of type (1,2) on the open subset 'U' of the 3-dimensional manifold 'M'

Tensor contractions are dealt with by the methods trace() and contract(): for instance, let us contract the tensor $T$ w.r.t. its first two arguments (positions 0 and 1), i.e. let us form the tensor $c$ of components $c_i = T^k_{\ \, k i}$:

c = t.trace(0,1)
print c

1-form on the open subset 'U' of the 3-dimensional manifold 'M'

An alternative to the writing trace(0,1) is to use the index notation to denote the contraction: the indices are given in a string inside the [] operator, with '^' in front of the contravariant indices and '_' in front of the covariant ones:

c1 = t['^k_ki']
print c1
c1 == c

1-form on the open subset 'U' of the 3-dimensional manifold 'M'

$\mathrm{True}$

The contraction is performed on the repeated index (here k); the letter denoting the remaining index (here i) is arbitrary:

t['^k_kj'] == c

$\mathrm{True}$

t['^b_ba'] == c

$\mathrm{True}$

It can even be replaced by a dot:

t['^k_k.'] == c

$\mathrm{True}$

LaTeX notations are allowed:

t['^{k}_{ki}'] == c

$\mathrm{True}$

The contraction $T^i_{\ j k} v^k$ of the tensor fields $T$ and $v$ is taken as follows (2 refers to the last index position of $T$ and 0 to the only index position of v):

tv = t.contract(2, v, 0)
print tv

tensor field of type (1,1) on the open subset 'U' of the 3-dimensional manifold 'M'

Since 2 corresponds to the last index position of $T$ and 0 to the first index position of $v$, a shortcut for the above is

tv1 = t.contract(v)
print tv1

tensor field of type (1,1) on the open subset 'U' of the 3-dimensional manifold 'M'

tv1 == tv

$\mathrm{True}$

Instead of contract(), the index notation, combined with the * operator, can be used to denote the contraction:

t['^i_jk']*v['^k'] == tv

$\mathrm{True}$

The non-repeated indices can be replaced by dots:

t['^._.k']*v['^k'] == tv

$\mathrm{True}$

Metric structures

A Riemannian metric on the manifold $\mathcal{M}$ is declared as follows:

g = M.riemann_metric('g')
print g

Riemannian metric 'g' on the 3-dimensional manifold 'M'

It is a symmetric tensor field of type (0,2):

g.parent()

$\mathcal{T}^{(0,2)}\left(\mathcal{M}\right)$

print g.parent()

free module T^(0,2)(M) of type-(0,2) tensors fields on the 3-dimensional manifold 'M'

g.symmetries()

symmetry: (0, 1); no antisymmetry

The metric is initialized by its components with respect to some vector frame. For instance, using the default frame of $\mathcal{M}$:

g[1,1], g[2,2], g[3,3] = 1, 1, 1
g.display()

$g = \mathrm{d} x\otimes \mathrm{d} x+\mathrm{d} y\otimes \mathrm{d} y+\mathrm{d} z\otimes \mathrm{d} z$

The components w.r.t. another vector frame are obtained as for any tensor field:

g.display(Y.frame(), Y)

$g = \mathrm{d} r\otimes \mathrm{d} r + r^{2} \mathrm{d} {\theta}\otimes \mathrm{d} {\theta} + r^{2} \sin\left({\theta}\right)^{2} \mathrm{d} {\phi}\otimes \mathrm{d} {\phi}$

Of course, the metric acts on vector pairs:

u.display() ; v.display(); print g(u,v) ; g(u,v).display()

$u = u_{x}\left(x, y, z\right) \frac{\partial}{\partial x } + u_{y}\left(x, y, z\right) \frac{\partial}{\partial y } + u_{z}\left(x, y, z\right) \frac{\partial}{\partial z }$

$v = \left( y + 1 \right) \frac{\partial}{\partial x } -x \frac{\partial}{\partial y } + x y z \frac{\partial}{\partial z }$

scalar field 'g(u,v)' on the open subset 'U' of the 3-dimensional manifold 'M'

$\begin{array}{llcl} g\left(u,v\right):& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & x y z u_{z}\left(x, y, z\right) + y u_{x}\left(x, y, z\right) - x u_{y}\left(x, y, z\right) + u_{x}\left(x, y, z\right) \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) \sin\left({\theta}\right)^{2} u_{z}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) - r \cos\left({\phi}\right) \sin\left({\theta}\right) u_{y}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) + {\left(r \sin\left({\phi}\right) \sin\left({\theta}\right) + 1\right)} u_{x}\left(r \cos\left({\phi}\right) \sin\left({\theta}\right), r \sin\left({\phi}\right) \sin\left({\theta}\right), r \cos\left({\theta}\right)\right) \end{array}$

The Levi-Civita connection associated to the metric $g$:

nabla = g.connection() 
print nabla ; nabla

Levi-Civita connection 'nabla_g' associated with the Riemannian metric 'g' on the 3-dimensional manifold 'M'

$\nabla_{g}$

The Christoffel symbols with respect to the manifold's default coordinates:

nabla.coef()[:]

[[[$0$, $0$, $0$], [$0$, $0$, $0$], [$0$, $0$, $0$]], [[$0$, $0$, $0$], [$0$, $0$, $0$], [$0$, $0$, $0$]], [[$0$, $0$, $0$], [$0$, $0$, $0$], [$0$, $0$, $0$]]]

The Christoffel symbols with respect to the coordinates $(r,\theta,\phi)$:

nabla.coef(Y.frame())[:, Y]

[[[$0$, $0$, $0$], [$0$, $-r$, $0$], [$0$, $0$, $-r \sin\left({\theta}\right)^{2}$]], [[$0$, $\frac{1}{r}$, $0$], [$\frac{1}{r}$, $0$, $0$], [$0$, $0$, $-\cos\left({\theta}\right) \sin\left({\theta}\right)$]], [[$0$, $0$, $\frac{1}{r}$], [$0$, $0$, $\frac{\cos\left({\theta}\right)}{\sin\left({\theta}\right)}$], [$\frac{1}{r}$, $\frac{\cos\left({\theta}\right)}{\sin\left({\theta}\right)}$, $0$]]]

A nice view is obtained via the method display() (by default, only the nonzero connection coefficients are shown):

nabla.display(frame=Y.frame(), chart=Y)

$\begin{array}{lcl} \Gamma_{ \phantom{\, r } \, {\theta} \, {\theta} }^{ \, r \phantom{\, {\theta} } \phantom{\, {\theta} } } & = & -r \\ \Gamma_{ \phantom{\, r } \, {\phi} \, {\phi} }^{ \, r \phantom{\, {\phi} } \phantom{\, {\phi} } } & = & -r \sin\left({\theta}\right)^{2} \\ \Gamma_{ \phantom{\, {\theta} } \, r \, {\theta} }^{ \, {\theta} \phantom{\, r } \phantom{\, {\theta} } } & = & \frac{1}{r} \\ \Gamma_{ \phantom{\, {\theta} } \, {\theta} \, r }^{ \, {\theta} \phantom{\, {\theta} } \phantom{\, r } } & = & \frac{1}{r} \\ \Gamma_{ \phantom{\, {\theta} } \, {\phi} \, {\phi} }^{ \, {\theta} \phantom{\, {\phi} } \phantom{\, {\phi} } } & = & -\cos\left({\theta}\right) \sin\left({\theta}\right) \\ \Gamma_{ \phantom{\, {\phi} } \, r \, {\phi} }^{ \, {\phi} \phantom{\, r } \phantom{\, {\phi} } } & = & \frac{1}{r} \\ \Gamma_{ \phantom{\, {\phi} } \, {\theta} \, {\phi} }^{ \, {\phi} \phantom{\, {\theta} } \phantom{\, {\phi} } } & = & \frac{\cos\left({\theta}\right)}{\sin\left({\theta}\right)} \\ \Gamma_{ \phantom{\, {\phi} } \, {\phi} \, r }^{ \, {\phi} \phantom{\, {\phi} } \phantom{\, r } } & = & \frac{1}{r} \\ \Gamma_{ \phantom{\, {\phi} } \, {\phi} \, {\theta} }^{ \, {\phi} \phantom{\, {\phi} } \phantom{\, {\theta} } } & = & \frac{\cos\left({\theta}\right)}{\sin\left({\theta}\right)} \end{array}$

The connection acting as a covariant derivative:

nab_v = nabla(v)
print nab_v ; nab_v.display()

tensor field 'nabla_g v' of type (1,1) on the open subset 'U' of the 3-dimensional manifold 'M'

$\nabla_{g} v = \frac{\partial}{\partial x }\otimes \mathrm{d} y-\frac{\partial}{\partial y }\otimes \mathrm{d} x + y z \frac{\partial}{\partial z }\otimes \mathrm{d} x + x z \frac{\partial}{\partial z }\otimes \mathrm{d} y + x y \frac{\partial}{\partial z }\otimes \mathrm{d} z$

Being a Levi-Civita connection, $\nabla_g$ is torsion.free:

print nabla.torsion() ; nabla.torsion().display()

tensor field of type (1,2) on the 3-dimensional manifold 'M'

$0$

In the present case, it is also flat:

print nabla.riemann() ; nabla.riemann().display()

tensor field 'Riem(g)' of type (1,3) on the 3-dimensional manifold 'M'

$\mathrm{Riem}\left(g\right) = 0$

Let us consider a non-flat metric, by changing $g_{rr}$ to $1/(1+r^2)$:

g[Y.frame(), 1,1, Y] = 1/(1+r^2)
g.display(Y.frame(), Y)

$g = \left( \frac{1}{r^{2} + 1} \right) \mathrm{d} r\otimes \mathrm{d} r + r^{2} \mathrm{d} {\theta}\otimes \mathrm{d} {\theta} + r^{2} \sin\left({\theta}\right)^{2} \mathrm{d} {\phi}\otimes \mathrm{d} {\phi}$

For convenience, we change the default chart on the domain $U$ to Y=$(U,(r,\theta,\phi))$:

U.set_default_chart(Y)

In this way, we do not have to specify Y when asking for coordinate expressions in terms of $(r,\theta,\phi)$:

g.display(Y.frame())

$g = \left( \frac{1}{r^{2} + 1} \right) \mathrm{d} r\otimes \mathrm{d} r + r^{2} \mathrm{d} {\theta}\otimes \mathrm{d} {\theta} + r^{2} \sin\left({\theta}\right)^{2} \mathrm{d} {\phi}\otimes \mathrm{d} {\phi}$

We recognize the metric of the hyperbolic space $\mathbb{H}^3$. Its expression in terms of the chart $(U,(x,y,z))$ is

g.display(X_U.frame(), X_U)

$g = \left( \frac{y^{2} + z^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} x\otimes \mathrm{d} x + \left( -\frac{x y}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} x\otimes \mathrm{d} y + \left( -\frac{x z}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} x\otimes \mathrm{d} z + \left( -\frac{x y}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} y\otimes \mathrm{d} x + \left( \frac{x^{2} + z^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} y\otimes \mathrm{d} y + \left( -\frac{y z}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} y\otimes \mathrm{d} z + \left( -\frac{x z}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} z\otimes \mathrm{d} x + \left( -\frac{y z}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} z\otimes \mathrm{d} y + \left( \frac{x^{2} + y^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} z\otimes \mathrm{d} z$

A matrix view of the components may be more appropriate:

g[X_U.frame(), :, X_U]

$\left(\begin{array}{rrr} \frac{y^{2} + z^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} & -\frac{x y}{x^{2} + y^{2} + z^{2} + 1} & -\frac{x z}{x^{2} + y^{2} + z^{2} + 1} \\ -\frac{x y}{x^{2} + y^{2} + z^{2} + 1} & \frac{x^{2} + z^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} & -\frac{y z}{x^{2} + y^{2} + z^{2} + 1} \\ -\frac{x z}{x^{2} + y^{2} + z^{2} + 1} & -\frac{y z}{x^{2} + y^{2} + z^{2} + 1} & \frac{x^{2} + y^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} \end{array}\right)$

We extend these components, a priori defined only on $U$, to the whole manifold $\mathcal{M}$, by demanding the same coordinate expressions in the frame associated to the chart X=$(\mathcal{M},(x,y,z))$:

g.add_comp_by_continuation(X.frame(), U, X)
g.display()

$g = \left( \frac{y^{2} + z^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} x\otimes \mathrm{d} x + \left( -\frac{x y}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} x\otimes \mathrm{d} y + \left( -\frac{x z}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} x\otimes \mathrm{d} z + \left( -\frac{x y}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} y\otimes \mathrm{d} x + \left( \frac{x^{2} + z^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} y\otimes \mathrm{d} y + \left( -\frac{y z}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} y\otimes \mathrm{d} z + \left( -\frac{x z}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} z\otimes \mathrm{d} x + \left( -\frac{y z}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} z\otimes \mathrm{d} y + \left( \frac{x^{2} + y^{2} + 1}{x^{2} + y^{2} + z^{2} + 1} \right) \mathrm{d} z\otimes \mathrm{d} z$

The Levi-Civita connection is automatically recomputed, after the change in $g$:

nabla = g.connection()

In particular, the Christoffel symbols are different:

nabla.display(only_nonredundant=True)

$\begin{array}{lcl} \Gamma_{ \phantom{\, x } \, x \, x }^{ \, x \phantom{\, x } \phantom{\, x } } & = & -\frac{x y^{2} + x z^{2} + x}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, x } \, x \, y }^{ \, x \phantom{\, x } \phantom{\, y } } & = & \frac{x^{2} y}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, x } \, x \, z }^{ \, x \phantom{\, x } \phantom{\, z } } & = & \frac{x^{2} z}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, x } \, y \, y }^{ \, x \phantom{\, y } \phantom{\, y } } & = & -\frac{x^{3} + x z^{2} + x}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, x } \, y \, z }^{ \, x \phantom{\, y } \phantom{\, z } } & = & \frac{x y z}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, x } \, z \, z }^{ \, x \phantom{\, z } \phantom{\, z } } & = & -\frac{x^{3} + x y^{2} + x}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, y } \, x \, x }^{ \, y \phantom{\, x } \phantom{\, x } } & = & -\frac{y^{3} + y z^{2} + y}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, y } \, x \, y }^{ \, y \phantom{\, x } \phantom{\, y } } & = & \frac{x y^{2}}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, y } \, x \, z }^{ \, y \phantom{\, x } \phantom{\, z } } & = & \frac{x y z}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, y } \, y \, y }^{ \, y \phantom{\, y } \phantom{\, y } } & = & -\frac{y z^{2} + {\left(x^{2} + 1\right)} y}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, y } \, y \, z }^{ \, y \phantom{\, y } \phantom{\, z } } & = & \frac{y^{2} z}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, y } \, z \, z }^{ \, y \phantom{\, z } \phantom{\, z } } & = & -\frac{y^{3} + {\left(x^{2} + 1\right)} y}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, z } \, x \, x }^{ \, z \phantom{\, x } \phantom{\, x } } & = & -\frac{z^{3} + {\left(y^{2} + 1\right)} z}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, z } \, x \, y }^{ \, z \phantom{\, x } \phantom{\, y } } & = & \frac{x y z}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, z } \, x \, z }^{ \, z \phantom{\, x } \phantom{\, z } } & = & \frac{x z^{2}}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, z } \, y \, y }^{ \, z \phantom{\, y } \phantom{\, y } } & = & -\frac{z^{3} + {\left(x^{2} + 1\right)} z}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, z } \, y \, z }^{ \, z \phantom{\, y } \phantom{\, z } } & = & \frac{y z^{2}}{x^{2} + y^{2} + z^{2} + 1} \\ \Gamma_{ \phantom{\, z } \, z \, z }^{ \, z \phantom{\, z } \phantom{\, z } } & = & -\frac{{\left(x^{2} + y^{2} + 1\right)} z}{x^{2} + y^{2} + z^{2} + 1} \end{array}$

nabla.display(frame=Y.frame(), chart=Y, only_nonredundant=True)

$\begin{array}{lcl} \Gamma_{ \phantom{\, r } \, r \, r }^{ \, r \phantom{\, r } \phantom{\, r } } & = & -\frac{r}{r^{2} + 1} \\ \Gamma_{ \phantom{\, r } \, {\theta} \, {\theta} }^{ \, r \phantom{\, {\theta} } \phantom{\, {\theta} } } & = & -r^{3} - r \\ \Gamma_{ \phantom{\, r } \, {\phi} \, {\phi} }^{ \, r \phantom{\, {\phi} } \phantom{\, {\phi} } } & = & -{\left(r^{3} + r\right)} \sin\left({\theta}\right)^{2} \\ \Gamma_{ \phantom{\, {\theta} } \, r \, {\theta} }^{ \, {\theta} \phantom{\, r } \phantom{\, {\theta} } } & = & \frac{1}{r} \\ \Gamma_{ \phantom{\, {\theta} } \, {\phi} \, {\phi} }^{ \, {\theta} \phantom{\, {\phi} } \phantom{\, {\phi} } } & = & -\cos\left({\theta}\right) \sin\left({\theta}\right) \\ \Gamma_{ \phantom{\, {\phi} } \, r \, {\phi} }^{ \, {\phi} \phantom{\, r } \phantom{\, {\phi} } } & = & \frac{1}{r} \\ \Gamma_{ \phantom{\, {\phi} } \, {\theta} \, {\phi} }^{ \, {\phi} \phantom{\, {\theta} } \phantom{\, {\phi} } } & = & \frac{\cos\left({\theta}\right)}{\sin\left({\theta}\right)} \end{array}$

The Riemann tensor is now

Riem = nabla.riemann()
print Riem ; Riem.display(Y.frame())

tensor field 'Riem(g)' of type (1,3) on the 3-dimensional manifold 'M'

$\mathrm{Riem}\left(g\right) = -r^{2} \frac{\partial}{\partial r }\otimes \mathrm{d} {\theta}\otimes \mathrm{d} r\otimes \mathrm{d} {\theta} + r^{2} \frac{\partial}{\partial r }\otimes \mathrm{d} {\theta}\otimes \mathrm{d} {\theta}\otimes \mathrm{d} r -r^{2} \sin\left({\theta}\right)^{2} \frac{\partial}{\partial r }\otimes \mathrm{d} {\phi}\otimes \mathrm{d} r\otimes \mathrm{d} {\phi} + r^{2} \sin\left({\theta}\right)^{2} \frac{\partial}{\partial r }\otimes \mathrm{d} {\phi}\otimes \mathrm{d} {\phi}\otimes \mathrm{d} r + \left( \frac{1}{r^{2} + 1} \right) \frac{\partial}{\partial {\theta} }\otimes \mathrm{d} r\otimes \mathrm{d} r\otimes \mathrm{d} {\theta} + \left( -\frac{1}{r^{2} + 1} \right) \frac{\partial}{\partial {\theta} }\otimes \mathrm{d} r\otimes \mathrm{d} {\theta}\otimes \mathrm{d} r -r^{2} \sin\left({\theta}\right)^{2} \frac{\partial}{\partial {\theta} }\otimes \mathrm{d} {\phi}\otimes \mathrm{d} {\theta}\otimes \mathrm{d} {\phi} + r^{2} \sin\left({\theta}\right)^{2} \frac{\partial}{\partial {\theta} }\otimes \mathrm{d} {\phi}\otimes \mathrm{d} {\phi}\otimes \mathrm{d} {\theta} + \left( \frac{1}{r^{2} + 1} \right) \frac{\partial}{\partial {\phi} }\otimes \mathrm{d} r\otimes \mathrm{d} r\otimes \mathrm{d} {\phi} + \left( -\frac{1}{r^{2} + 1} \right) \frac{\partial}{\partial {\phi} }\otimes \mathrm{d} r\otimes \mathrm{d} {\phi}\otimes \mathrm{d} r + r^{2} \frac{\partial}{\partial {\phi} }\otimes \mathrm{d} {\theta}\otimes \mathrm{d} {\theta}\otimes \mathrm{d} {\phi} -r^{2} \frac{\partial}{\partial {\phi} }\otimes \mathrm{d} {\theta}\otimes \mathrm{d} {\phi}\otimes \mathrm{d} {\theta}$

Note that it can be accessed directely via the metric, without any explicit mention of the connection:

g.riemann() is nabla.riemann()

$\mathrm{True}$

The Ricci tensor is

Ric = g.ricci()
print Ric ; Ric.display(Y.frame())

field of symmetric bilinear forms 'Ric(g)' on the 3-dimensional manifold 'M'

$\mathrm{Ric}\left(g\right) = \left( -\frac{2}{r^{2} + 1} \right) \mathrm{d} r\otimes \mathrm{d} r -2 \, r^{2} \mathrm{d} {\theta}\otimes \mathrm{d} {\theta} -2 \, r^{2} \sin\left({\theta}\right)^{2} \mathrm{d} {\phi}\otimes \mathrm{d} {\phi}$

The Weyl tensor is:

C = g.weyl()
print C ; C.display()

tensor field 'C(g)' of type (1,3) on the 3-dimensional manifold 'M'

$\mathrm{C}\left(g\right) = 0$

The Weyl tensor vanishes identically because the dimension of $\mathcal{M}$ is 3.

Finally, the Ricci scalar is

R = g.ricci_scalar()
print R ; R.display()

scalar field 'r(g)' on the 3-dimensional manifold 'M'

$\begin{array}{llcl} \mathrm{r}\left(g\right):& \mathcal{M} & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & -6 \\ \mbox{on}\ U : & \left(r, {\theta}, {\phi}\right) & \longmapsto & -6 \end{array}$

We recover the fact that $\mathbb{H}^3$ is a Riemannian manifold of constant negative curvature.

Tensor transformations induced by a metric

The most important tensor transformation induced by the metric $g$ is the so-called musical isomorphism, or index raising and index lowering:

print t

tensor field 'T' of type (1,2) on the open subset 'U' of the 3-dimensional manifold 'M'

t.display()

$T = \left( r^{2} \cos\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + 1 \right) \frac{\partial}{\partial x }\otimes \mathrm{d} y\otimes \mathrm{d} x + r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) \sin\left({\theta}\right)^{2} \frac{\partial}{\partial z }\otimes \mathrm{d} y\otimes \mathrm{d} x$

t.display(X_U.frame(), X_U)

$T = \left( x^{2} + 1 \right) \frac{\partial}{\partial x }\otimes \mathrm{d} y\otimes \mathrm{d} x + x y z \frac{\partial}{\partial z }\otimes \mathrm{d} y\otimes \mathrm{d} x$

Raising the last index of $T$ with $g$:

s = t.up(g, 2)
print s

tensor field of type (2,1) on the open subset 'U' of the 3-dimensional manifold 'M'

Raising all the covariant indices of $T$ (i.e. those at the positions 1 and 2):

s = t.up(g)
print s

tensor field of type (3,0) on the open subset 'U' of the 3-dimensional manifold 'M'

s = t.down(g)
print s

tensor field of type (0,3) on the open subset 'U' of the 3-dimensional manifold 'M'

Hodge duality

The volume 3-form (Levi-Civita tensor) associated with the metric $g$ is

epsilon = g.volume_form()
print epsilon ; epsilon.display()

3-form 'eps_g' on the 3-dimensional manifold 'M'

$\epsilon_{g} = \left( \frac{1}{\sqrt{x^{2} + y^{2} + z^{2} + 1}} \right) \mathrm{d} x\wedge \mathrm{d} y\wedge \mathrm{d} z$

epsilon.display(Y.frame())

$\epsilon_{g} = \left( \frac{r^{2} \sin\left({\theta}\right)}{\sqrt{r^{2} + 1}} \right) \mathrm{d} r\wedge \mathrm{d} {\theta}\wedge \mathrm{d} {\phi}$

print f ; f.display()

scalar field 'f' on the open subset 'U' of the 3-dimensional manifold 'M'

$\begin{array}{llcl} f:& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & z^{3} + y^{2} + x \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right) \end{array}$

sf = f.hodge_star(g)
print sf ; sf.display()

3-form '*f' on the open subset 'U' of the 3-dimensional manifold 'M'

$\star f = \left( \frac{r^{3} \cos\left({\theta}\right)^{3} + r^{2} \sin\left({\phi}\right)^{2} \sin\left({\theta}\right)^{2} + r \cos\left({\phi}\right) \sin\left({\theta}\right)}{\sqrt{r^{2} + 1}} \right) \mathrm{d} x\wedge \mathrm{d} y\wedge \mathrm{d} z$

We check the classical formula $\star f = f\, \epsilon_g$, or, more precisely, $\star f = f\, \epsilon_g|_U$ (for $f$ is defined on $U$ only):

sf == f * epsilon.restrict(U)

$\mathrm{True}$

The Hodge dual of a 1-form is a 2-form:

print om ; om.display()

1-form 'omega' on the open subset 'U' of the 3-dimensional manifold 'M'

$\omega = r^{2} \sin\left({\theta}\right)^{2} \mathrm{d} x + r \cos\left({\theta}\right) \mathrm{d} y + \left( r \cos\left({\phi}\right) \sin\left({\theta}\right) - r \cos\left({\theta}\right) \right) \mathrm{d} z$

som = om.hodge_star(g)
print som ; som.display()

2-form '*omega' on the open subset 'U' of the 3-dimensional manifold 'M'

$\star \omega = \left( \frac{r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\theta}\right)^{3} - r^{3} \cos\left({\theta}\right)^{3} - r \cos\left({\theta}\right) + {\left(r^{3} {\left(\cos\left({\phi}\right) + \sin\left({\phi}\right)\right)} \cos\left({\theta}\right)^{2} + r \cos\left({\phi}\right)\right)} \sin\left({\theta}\right)}{\sqrt{r^{2} + 1}} \right) \mathrm{d} x\wedge \mathrm{d} y + \left( -\frac{r^{4} \cos\left({\phi}\right) \sin\left({\phi}\right) \sin\left({\theta}\right)^{4} - r^{3} \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) \sin\left({\theta}\right) + {\left(\cos\left({\phi}\right) \sin\left({\phi}\right) + \sin\left({\phi}\right)^{2}\right)} r^{3} \cos\left({\theta}\right) \sin\left({\theta}\right)^{2} + r \cos\left({\theta}\right)}{\sqrt{r^{2} + 1}} \right) \mathrm{d} x\wedge \mathrm{d} z + \left( \frac{r^{4} \cos\left({\phi}\right)^{2} \sin\left({\theta}\right)^{4} - r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\theta}\right) + {\left({\left(\cos\left({\phi}\right)^{2} + \cos\left({\phi}\right) \sin\left({\phi}\right)\right)} r^{3} \cos\left({\theta}\right) + r^{2}\right)} \sin\left({\theta}\right)^{2}}{\sqrt{r^{2} + 1}} \right) \mathrm{d} y\wedge \mathrm{d} z$

The Hodge dual of a 2-form is a 1-form:

print a

2-form 'A' on the open subset 'U' of the 3-dimensional manifold 'M'

sa = a.hodge_star(g)
print sa ; sa.display()

1-form '*A' on the open subset 'U' of the 3-dimensional manifold 'M'

$\star A = \left( \frac{3 \, r^{5} \cos\left({\theta}\right)^{5} + 3 \, r^{3} \cos\left({\theta}\right)^{3} + {\left(3 \, r^{6} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) - 2 \, r^{5} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) - 2 \, r^{4} \cos\left({\phi}\right) \sin\left({\phi}\right)^{3}\right)} \sin\left({\theta}\right)^{4} + {\left(2 \, r^{4} \cos\left({\theta}\right) \sin\left({\phi}\right)^{3} + {\left(\sin\left({\phi}\right)^{3} - \sin\left({\phi}\right)\right)} r^{3}\right)} \sin\left({\theta}\right)^{3} + {\left(3 \, r^{5} \cos\left({\theta}\right)^{3} \sin\left({\phi}\right)^{2} - 2 \, r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) + r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right) - 2 \, r^{2} \cos\left({\phi}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{2} + {\left(2 \, r^{4} \cos\left({\theta}\right)^{3} \sin\left({\phi}\right) + r^{3} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} + 2 \, r^{2} \cos\left({\theta}\right) \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)}{\sqrt{r^{2} + 1}} \right) \mathrm{d} x + \left( -\frac{r^{3} \cos\left({\theta}\right)^{3} - {\left(3 \, {\left(\sin\left({\phi}\right)^{2} - 1\right)} r^{6} \cos\left({\theta}\right)^{2} - 2 \, r^{5} \cos\left({\theta}\right) \sin\left({\phi}\right)^{2} - 2 \, {\left(\sin\left({\phi}\right)^{4} - \sin\left({\phi}\right)^{2}\right)} r^{4}\right)} \sin\left({\theta}\right)^{4} + {\left(2 \, r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right) \sin\left({\phi}\right)^{2} + {\left(\cos\left({\phi}\right) \sin\left({\phi}\right)^{2} - \cos\left({\phi}\right)\right)} r^{3}\right)} \sin\left({\theta}\right)^{3} + {\left(3 \, r^{6} \cos\left({\theta}\right)^{4} + 3 \, r^{5} \cos\left({\phi}\right) \cos\left({\theta}\right)^{3} \sin\left({\phi}\right) + 3 \, r^{4} \cos\left({\theta}\right)^{2} - {\left(\sin\left({\phi}\right)^{2} - 1\right)} r^{3} \cos\left({\theta}\right)\right)} \sin\left({\theta}\right)^{2} + r \cos\left({\theta}\right) - {\left(r^{3} {\left(\cos\left({\phi}\right) + \sin\left({\phi}\right)\right)} \cos\left({\theta}\right)^{2} + r \cos\left({\phi}\right)\right)} \sin\left({\theta}\right)}{\sqrt{r^{2} + 1}} \right) \mathrm{d} y + \left( \frac{2 \, r^{5} \sin\left({\phi}\right) \sin\left({\theta}\right)^{5} + {\left(3 \, r^{6} \cos\left({\theta}\right)^{3} \sin\left({\phi}\right) + 2 \, r^{4} \cos\left({\phi}\right)^{2} \cos\left({\theta}\right) \sin\left({\phi}\right) + 2 \, r^{3} \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)^{3} - {\left(2 \, r^{4} \cos\left({\phi}\right) \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) + {\left(\cos\left({\phi}\right) \sin\left({\phi}\right) + 1\right)} r^{3} \cos\left({\theta}\right)\right)} \sin\left({\theta}\right)^{2} - r \cos\left({\theta}\right) - {\left(3 \, r^{5} \cos\left({\phi}\right) \cos\left({\theta}\right)^{4} - r^{3} \cos\left({\theta}\right)^{2} \sin\left({\phi}\right)\right)} \sin\left({\theta}\right)}{\sqrt{r^{2} + 1}} \right) \mathrm{d} z$

Finally, the Hodge dual of a 3-form is a 0-form:

print da ; da.display()

3-form 'dA' on the open subset 'U' of the 3-dimensional manifold 'M'

$\mathrm{d}A = \left( -2 \, {\left(3 \, r^{3} \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) + r \sin\left({\phi}\right)\right)} \sin\left({\theta}\right) - 1 \right) \mathrm{d} x\wedge \mathrm{d} y\wedge \mathrm{d} z$

sda = da.hodge_star(g)
print sda ; sda.display()

scalar field '*dA' on the open subset 'U' of the 3-dimensional manifold 'M'

$\begin{array}{llcl} \star \mathrm{d}A:& U & \longrightarrow & \mathbb{R} \\ & \left(x, y, z\right) & \longmapsto & -{\left(6 \, y z^{2} + 2 \, y + 1\right)} \sqrt{x^{2} + y^{2} + z^{2} + 1} \\ & \left(r, {\theta}, {\phi}\right) & \longmapsto & -\sqrt{r^{2} \cos\left({\theta}\right)^{2} + r^{2} \sin\left({\theta}\right)^{2} + 1} {\left(2 \, {\left(3 \, r^{3} \cos\left({\theta}\right)^{2} \sin\left({\phi}\right) + r \sin\left({\phi}\right)\right)} \sin\left({\theta}\right) + 1\right)} \end{array}$

In dimension 3 and for a Riemannian metric, the Hodge star is idempotent:

sf.hodge_star(g) == f

$\mathrm{True}$

som.hodge_star(g) == om

$\mathrm{True}$

sa.hodge_star(g) == a

$\mathrm{True}$

sda.hodge_star(g) == da

$\mathrm{True}$

Getting help

To get the list of functions (methods) that can be called on a object, type the name of the object, followed by a dot and the TAB key, e.g.

sa.<tab>

To get information on an object or a method, use the question mark:

nabla?

File: /projects/sage/sage-6.9/local/lib/python2.7/site-packages/sage/geometry/manifolds/connection.py
Signature : nabla()
Docstring :
Levi-Civita connection on a pseudo-Riemannian manifold.

Given a differentiable manifold M endowed with a pseudo-Riemannian
metric g and denoting by mathcal{X}(M) the C^infty(M)-module of
vector fields on M (cf. "VectorFieldModule"), the *Levi-Civita
connection associated with* g is the unique operator

   begin{array}{cccc} nabla: & mathcal{X}(M) x
   mathcal{X}(M) & longrightarrow &          mathcal{X}(M) 
   & (u,v) & longmapsto & nabla_u v end{array}

that

* is bilinear when considering mathcal{X}(M) as a vector space
  over RR

* is C^infty(M)-linear w.r.t. the first argument: forall fin
  C^infty(M), nabla_{fu} v = fnabla_u v

* obeys Leibniz rule w.r.t. the second argument: forall fin
  C^infty(M), nabla_u (f v) = df(u), v + f  nabla_u v

* is torsion-free

* is compatible with g: forall (u,v,w)in mathcal{X}(M)^3,
  u(g(v,w)) = g(nabla_u v, w) + g(v, nabla_u w)

The Levi-Civita connection nabla gives birth to the *covariant
derivative operator* acting on tensor fields, denoted by the same
symbol:

   begin{array}{cccc} nabla: &  T^{(k,l)}(M) & longrightarrow &
   T^{(k,l+1)}(M)         & t & longmapsto & nabla t
   end{array}

where T^{(k,l)}(M) stands for the C^infty(M)-module of tensor
fields of type (k,l) on M (cf. "TensorFieldModule"), with the
convention T^{(0,0)}(M):=C^infty(M). For a vector field v,  the
covariant derivative nabla v is a type-(1,1) tensor field such
that

   forall u inmathcal{X}(M),    nabla_u v = nabla v(., u)

More generally for any tensor field tin T^{(k,l)}(M), we have

   forall u inmathcal{X}(M),    nabla_u t = nabla t(...,
   u)

Note: The above convention means that, in terms of index
  notation, the "derivation index" in nabla t is the *last* one:

     nabla_c t^{a_1... a_k}_{quadquad b_1... b_l} =
     (nabla t)^{a_1... a_k}_{quadquad b_1... b_l c}

INPUT:

* "metric" -- the metric g defining the Levi-Civita connection,
  as an instance of class "Metric"

* "name" -- name given to the connection

* "latex_name" -- (default: "None") LaTeX symbol to denote the
  connection

* "init_coef" -- (default: True) determines whether the
  Chrsitoffel symbols are initialized (in the top charts on the
  domain, i.e. disregarding the subcharts)

EXAMPLES:

Levi-Civita connection associated with the Euclidean metric on
RR^3 expressed in spherical coordinates:

   sage: Manifold._clear_cache_() # for doctests only
   sage: forget() # for doctests only
   sage: M = Manifold(3, 'R^3', start_index=1)
   sage: c_spher.<r,th,ph> = M.chart(r'r:[0,+oo) th:[0,pi]:theta ph:[0,2*pi):phi')
   sage: g = M.metric('g')
   sage: g[1,1], g[2,2], g[3,3] = 1, r^2 , (r*sin(th))^2
   sage: g.display()
   g = dr*dr + r^2 dth*dth + r^2*sin(th)^2 dph*dph
   sage: from sage.geometry.manifolds.connection import LeviCivitaConnection
   sage: nab = LeviCivitaConnection(g, 'nabla', r'nabla') ; nab
   Levi-Civita connection 'nabla' associated with the pseudo-Riemannian metric 'g' on the 3-dimensional manifold 'R^3'

Let us check that the connection is compatible with the metric:

   sage: Dg = nab(g) ; Dg
   tensor field 'nabla g' of type (0,3) on the 3-dimensional manifold 'R^3'
   sage: Dg == 0
   True

and that it is torsionless:

   sage: nab.torsion() == 0
   True
   sage: sage.geometry.manifolds.connection.AffConnection.torsion(nab) == 0  # forces the computation of the torsion
   True

The connection coefficients in the manifold's default frame are
Christoffel symbols, since the default frame is a coordinate frame:

   sage: M.default_frame()
   coordinate frame (R^3, (d/dr,d/dth,d/dph))
   sage: nab.coef()
   3-indices components w.r.t. coordinate frame (R^3, (d/dr,d/dth,d/dph)), with symmetry on the index positions (1, 2)
   sage: # note that the Christoffel symbols are symmetric with respect to their last two indices (positions (1,2))
   sage: nab.coef()[:]
   [[[0, 0, 0], [0, -r, 0], [0, 0, -r*sin(th)^2]],
   [[0, 1/r, 0], [1/r, 0, 0], [0, 0, -cos(th)*sin(th)]],
   [[0, 0, 1/r], [0, 0, cos(th)/sin(th)], [1/r, cos(th)/sin(th), 0]]]

g.ricci_scalar?

File: /projects/sage/sage-6.9/local/lib/python2.7/site-packages/sage/geometry/manifolds/metric.py
Signature : g.ricci_scalar(self, name=None, latex_name=None)
Docstring :
Return the metric's Ricci scalar.

The Ricci scalar is the scalar field r defined from the Ricci
tensor Ric and the metric tensor g by

   r = g^{ij} Ric_{ij}

INPUT:

* "name" -- (default: "None") name given to the Ricci scalar; if
  none, it is set to "r(g)", where "g" is the metric's name

* "latex_name" -- (default: "None") LaTeX symbol to denote the
  Ricci scalar; if none, it is set to "r(g)", where "g" is the
  metric's name

OUTPUT:

* the Ricci scalar r, as an instance of "ScalarField"

EXAMPLES:

Ricci scalar of the standard metric on the 2-sphere:

   sage: Manifold._clear_cache_() # for doctests only
   sage: M = Manifold(2, 'S^2', start_index=1)
   sage: U = M.open_subset('U') # the complement of a meridian (domain of spherical coordinates)
   sage: c_spher.<th,ph> = U.chart(r'th:(0,pi):theta ph:(0,2*pi):phi')
   sage: a = var('a') # the sphere radius
   sage: g = U.metric('g')
   sage: g[1,1], g[2,2] = a^2, a^2*sin(th)^2
   sage: g.display() # standard metric on the 2-sphere of radius a:
   g = a^2 dth*dth + a^2*sin(th)^2 dph*dph
   sage: g.ricci_scalar()
   scalar field 'r(g)' on the open subset 'U' of the 2-dimensional manifold 'S^2'
   sage: g.ricci_scalar().display() # The Ricci scalar is constant:
   r(g): U --> R
      (th, ph) |--> 2/a^2

Using a double question mark leads directly to the Python source code (Sage and SageManifolds are open source, aren't they ?)

g.ricci_scalar??

   File: /projects/sage/sage-6.9/local/lib/python2.7/site-packages/sage/geometry/manifolds/metric.py
   Source:
       def ricci_scalar(self, name=None, latex_name=None):
        r"""
        Return the metric's Ricci scalar.

        The Ricci scalar is the scalar field `r` defined from the Ricci tensor
        `Ric` and the metric tensor `g` by

        .. MATH::

            r = g^{ij} Ric_{ij}

        INPUT:

        - ``name`` -- (default: ``None``) name given to the Ricci scalar;
          if none, it is set to "r(g)", where "g" is the metric's name
        - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the
          Ricci scalar; if none, it is set to "\\mathrm{r}(g)", where "g"
          is the metric's name

        OUTPUT:

        - the Ricci scalar `r`, as an instance of
          :class:`~sage.geometry.manifolds.scalarfield.ScalarField`

        EXAMPLES:

        Ricci scalar of the standard metric on the 2-sphere::

            sage: Manifold._clear_cache_() # for doctests only
            sage: M = Manifold(2, 'S^2', start_index=1)
            sage: U = M.open_subset('U') # the complement of a meridian (domain of spherical coordinates)
            sage: c_spher.<th,ph> = U.chart(r'th:(0,pi):\theta ph:(0,2*pi):\phi')
            sage: a = var('a') # the sphere radius
            sage: g = U.metric('g')
            sage: g[1,1], g[2,2] = a^2, a^2*sin(th)^2
            sage: g.display() # standard metric on the 2-sphere of radius a:
            g = a^2 dth*dth + a^2*sin(th)^2 dph*dph
            sage: g.ricci_scalar()
            scalar field 'r(g)' on the open subset 'U' of the 2-dimensional manifold 'S^2'
            sage: g.ricci_scalar().display() # The Ricci scalar is constant:
            r(g): U --> R
               (th, ph) |--> 2/a^2

        """
        if self._ricci_scalar is None:
            manif = self._domain._manifold
            ric = self.ricci()
            ig = self.inverse()
            frame = ig.common_basis(ric)
            cric = ric._components[frame]
            cig = ig._components[frame]
            rsum1 = 0
            for i in manif.irange():
                rsum1 += cig[[i,i]] * cric[[i,i]]
            rsum2 = 0
            for i in manif.irange():
                for j in manif.irange(start=i+1):
                    rsum2 += cig[[i,j]] * cric[[i,j]]
            self._ricci_scalar = rsum1 + 2*rsum2
            if name is None:
                self._ricci_scalar._name = "r(" + self._name + ")"
            else:
                self._ricci_scalar._name = name
            if latex_name is None:
                self._ricci_scalar._latex_name = r"\mathrm{r}\left(" + \
                                                 self._latex_name + r"\right)"
            else:
                self._ricci_scalar._latex_name = latex_name
        return self._ricci_scalar

Going further

Have a look at the examples on SageManifolds page, especially the 2-dimensional sphere example for usage on a non-parallelizable manifold (each scalar field has to be defined in at least two coordinate charts, the module $\mathcal{X}(\mathcal{M})$ is no longer free and each tensor field has to be defined in at least two vector frames).