This worksheet provides a short introduction to SageManifolds (version 1.0, as included in SageMath 7.5).

Click here to download the worksheet file (ipynb format). To run it, you must start SageMath with the Jupyter notebook, via the command `sage -n jupyter`

In [1]:

```
version()
```

Out[1]:

First we set up the notebook to display mathematical objects using LaTeX rendering:

In [2]:

```
%display latex
```

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

In [3]:

```
M = Manifold(3, 'M', latex_name=r'\mathcal{M}', start_index=1)
```

- 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 stands for a mere Python variable, which refers to the manifold object in the computer memory, while the string`'M'`

is the mathematical symbol chosen for the manifold. - The optional argument
`latex_name=r'\mathcal{M}'`

sets the LaTeX symbol to display 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). If the argument`latex_name`

is not provided by the user, it is set to the string used as the second argument (here`'M'`

) - The optional 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`

.

Note that the default base field is $\mathbb{R}$. If we would have used the optional
argument `field='complex'`

, we would have defined a manifold over $\mathbb{C}$. See
list of all options more details.

If we ask for M, it is displayed via its LaTeX symbol:

In [4]:

```
M
```

Out[4]:

If we use the `print`

function instead, we get a short description of the object:

In [5]:

```
print(M)
```

In [6]:

```
type(M)
```

Out[6]:

In [7]:

```
category(M)
```

Out[7]:

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

In [8]:

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

In [9]:

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

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:

In [10]:

```
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 symbol of a coordinate if the latter is different from the coordinate name (an example will be provided below).

In [11]:

```
print(X)
```

In [12]:

```
X
```

Out[12]:

In [13]:

```
X[1]
```

Out[13]:

In [14]:

```
X[2]
```

Out[14]:

In [15]:

```
X[3]
```

Out[15]:

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

In [16]:

```
X[:]
```

Out[16]:

`<x,y,z>`

used in the chart declaration, each coordinate can be accessed directly via its name:

In [17]:

```
z is X[3]
```

Out[17]:

Coordinates are SageMath symbolic expressions:

In [18]:

```
type(z)
```

Out[18]:

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

In [19]:

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

Out[19]:

In [20]:

```
f.display()
```

Out[20]:

In [21]:

```
f(1,2,3)
```

Out[21]:

They belong to SageManifolds class CoordFunctionSymb:

In [22]:

```
type(f)
```

Out[22]:

In [23]:

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

results in

In [24]:

```
f0 + g0
```

Out[24]:

In [25]:

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

Out[25]:

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

In [26]:

```
(f0 + g0).simplify_trig()
```

Out[26]:

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

In [27]:

```
f0
```

Out[27]:

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

In [28]:

```
f1
```

Out[28]:

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

In [29]:

```
f1.display()
```

Out[29]:

Note that the method `expr()`

returns the underlying symbolic expression:

In [30]:

```
f1.expr()
```

Out[30]:

In [31]:

```
type(f1.expr())
```

Out[31]:

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):

In [32]:

```
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$:

In [33]:

```
X_U = X.restrict(U) ; X_U
```

Out[33]:

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

In [34]:

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

Out[34]:

*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 the coordinate $r$, there are only two fields, since the LaTeX symbol has not to be specified. The LaTeX symbols are used for the outputs:

In [35]:

```
th, ph
```

Out[35]:

In [36]:

```
Y[2], Y[3]
```

Out[36]:

In [37]:

```
assumptions()
```

Out[37]:

They are used in simplifications:

In [38]:

```
simplify(abs(r))
```

Out[38]:

In [39]:

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

Out[39]:

In [40]:

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

In [41]:

```
transit_Y_to_X
```

Out[41]:

In [42]:

```
transit_Y_to_X.display()
```

Out[42]:

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

In [43]:

```
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()
```

Out[43]:

**atlas** (the "user atlas", not the maximal atlas!) contains three charts:

In [44]:

```
M.atlas()
```

Out[44]:

In [45]:

```
M.default_chart()
```

Out[45]:

Each open subset has its own atlas (since an open subset of a manifold is a manifold by itself):

In [46]:

```
U.atlas()
```

Out[46]:

In [47]:

```
U.default_chart()
```

Out[47]:

`'threejs'`

or `'jmol'`

for interactive 3D graphics):

In [48]:

```
viewer3D = 'threejs' # must be 'threejs', 'jmol', 'tachyon' or None (default)
```

In [49]:

```
graph = Y.plot(X)
show(graph, viewer=viewer3D)
```

In [50]:

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

In [51]:

```
graph = X_U.plot(Y)
show(graph, viewer=viewer3D, axes_labels=['r','theta','phi'])
```

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

In [52]:

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

Out[52]:

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

In [53]:

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

Out[53]:

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

In [54]:

```
p in M
```

Out[54]:

It is also in $U$:

In [55]:

```
p in U
```

Out[55]:

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

In [56]:

```
p.coord(X)
```

Out[56]:

In [57]:

```
p.coord()
```

Out[57]:

In [58]:

```
X(p)
```

Out[58]:

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

In [59]:

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

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

In [60]:

```
q in U
```

Out[60]:

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

In [61]:

```
try:
q.coord(Y)
except ValueError as exc:
print("Error: " + str(exc))
```

but we can for point $p$:

In [62]:

```
p.coord(Y)
```

Out[62]:

In [63]:

```
Y(p)
```

Out[63]:

Points can be compared:

In [64]:

```
q == p
```

Out[64]:

In [65]:

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

Out[65]:

**elements**, whose **parents** are the manifold on which they have been defined:

In [66]:

```
p.parent()
```

Out[66]:

In [67]:

```
q.parent()
```

Out[67]:

In [68]:

```
p1.parent()
```

Out[68]:

A scalar field is a differentiable mapping $U \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):

In [69]:

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

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

In [70]:

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

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

In [71]:

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

In [72]:

```
f(p)
```

Out[72]:

The method `display()`

provides the expression of the scalar field in terms of a given chart:

In [73]:

```
f.display(X_U)
```

Out[73]:

`display()`

shows 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):

In [74]:

```
f.display()
```

Out[74]:

In [75]:

```
f.display(Y)
```

Out[75]:

In [76]:

```
f.coord_function(X_U)
```

Out[76]:

In [77]:

```
f.coord_function(X_U).display()
```

Out[77]:

In [78]:

```
f.coord_function(Y)
```

Out[78]:

In [79]:

```
f.coord_function(Y).display()
```

Out[79]:

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

In [80]:

```
f.expr(X_U)
```

Out[80]:

In [81]:

```
f.expr(Y)
```