Coordinate Charts

The class Chart implements coordinate charts on a topological manifold over a topological field \(K\). The subclass RealChart is devoted to the case \(K=\RR\), for which the concept of coordinate range is meaningful. Moreover, RealChart is endowed with some plotting capabilities (cf. method plot()).

Transition maps between charts are implemented via the class CoordChange.

AUTHORS:

  • Eric Gourgoulhon, Michal Bejger (2013-2015) : initial version
  • Travis Scrimshaw (2015): review tweaks

REFERENCES:

sage.manifolds.chart.Chart

Chart on a topological manifold.

Given a topological manifold \(M\) of dimension \(n\) over a topological field \(K\), a chart on \(M\) is a pair \((U, \varphi)\), where \(U\) is an open subset of \(M\) and \(\varphi : U \rightarrow V \subset K^n\) is a homeomorphism from \(U\) to an open subset \(V\) of \(K^n\).

The components \((x^1, \ldots, x^n)\) of \(\varphi\), defined by \(\varphi(p) = (x^1(p), \ldots, x^n(p)) \in K^n\) for any point \(p \in U\), are called the coordinates of the chart \((U, \varphi)\).

INPUT:

  • domain – open subset \(U\) on which the chart is defined (must be an instance of TopologicalManifold)
  • coordinates – (default: '' (empty string)) the string defining the coordinate symbols, see below
  • names – (default: None) unused argument, except if coordinates is not provided; it must then be a tuple containing the coordinate symbols (this is guaranteed if the shortcut operator <,> is used)
  • calc_method – (default: None) string defining the calculus method for computations involving coordinates of the chart; must be one of
    • 'SR': Sage’s default symbolic engine (Symbolic Ring)
    • 'sympy': SymPy
    • None: the default of CalculusMethod will be used

The string coordinates has the space ' ' as a separator and each item has at most two fields, separated by a colon (:):

  1. the coordinate symbol (a letter or a few letters);
  2. (optional) the LaTeX spelling of the coordinate, if not provided the coordinate symbol given in the first field will be used.

If it contains any LaTeX expression, the string coordinates must be declared with the prefix ‘r’ (for “raw”) to allow for a proper treatment of LaTeX’s backslash character (see examples below). If no LaTeX spelling is to be set for any coordinate, the argument coordinates can be omitted when the shortcut operator <,> is used via Sage preparser (see examples below).

EXAMPLES:

A chart on a complex 2-dimensional topological manifold:

sage: M = Manifold(2, 'M', field='complex', structure='topological')
sage: X = M.chart('x y'); X
Chart (M, (x, y))
sage: latex(X)
\left(M,(x, y)\right)
sage: type(X)
<class 'sage.manifolds.chart.Chart'>

To manipulate the coordinates \((x,y)\) as global variables, one has to set:

sage: x,y = X[:]

However, a shortcut is to use the declarator <x,y> in the left-hand side of the chart declaration (there is then no need to pass the string 'x y' to chart()):

sage: M = Manifold(2, 'M', field='complex', structure='topological')
sage: X.<x,y> = M.chart(); X
Chart (M, (x, y))

The coordinates are then immediately accessible:

sage: y
y
sage: x is X[0] and y is X[1]
True

Note that x and y declared in <x,y> are mere Python variable names and do not have to coincide with the coordinate symbols; for instance, one may write:

sage: M = Manifold(2, 'M', field='complex', structure='topological')
sage: X.<x1,y1> = M.chart('x y'); X
Chart (M, (x, y))

Then y is not known as a global Python variable and the coordinate \(y\) is accessible only through the global variable y1:

sage: y1
y
sage: latex(y1)
y
sage: y1 is X[1]
True

However, having the name of the Python variable coincide with the coordinate symbol is quite convenient; so it is recommended to declare:

sage: M = Manifold(2, 'M', field='complex', structure='topological')
sage: X.<x,y> = M.chart()

In the above example, the chart X covers entirely the manifold M:

sage: X.domain()
Complex 2-dimensional topological manifold M

Of course, one may declare a chart only on an open subset of M:

sage: U = M.open_subset('U')
sage: Y.<z1, z2> = U.chart(r'z1:\zeta_1 z2:\zeta_2'); Y
Chart (U, (z1, z2))
sage: Y.domain()
Open subset U of the Complex 2-dimensional topological manifold M

In the above declaration, we have also specified some LaTeX writing of the coordinates different from the text one:

sage: latex(z1)
{\zeta_1}

Note the prefix r in front of the string r'z1:\zeta_1 z2:\zeta_2'; it makes sure that the backslash character is treated as an ordinary character, to be passed to the LaTeX interpreter.

Coordinates are Sage symbolic variables (see sage.symbolic.expression):

sage: type(z1)
<type 'sage.symbolic.expression.Expression'>

In addition to the Python variable name provided in the operator <.,.>, the coordinates are accessible by their indices:

sage: Y[0], Y[1]
(z1, z2)

The index range is that declared during the creation of the manifold. By default, it starts at 0, but this can be changed via the parameter start_index:

sage: M1 = Manifold(2, 'M_1', field='complex', structure='topological',
....:               start_index=1)
sage: Z.<u,v> = M1.chart()
sage: Z[1], Z[2]
(u, v)

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

sage: Y[:]
(z1, z2)

Some partial sets of coordinates:

sage: Y[:1]
(z1,)
sage: Y[1:]
(z2,)

Each constructed chart is automatically added to the manifold’s user atlas:

sage: M.atlas()
[Chart (M, (x, y)), Chart (U, (z1, z2))]

and to the atlas of the chart’s domain:

sage: U.atlas()
[Chart (U, (z1, z2))]

Manifold subsets have a default chart, which, unless changed via the method set_default_chart(), is the first defined chart on the subset (or on a open subset of it):

sage: M.default_chart()
Chart (M, (x, y))
sage: U.default_chart()
Chart (U, (z1, z2))

The default charts are not privileged charts on the manifold, but rather charts whose name can be skipped in the argument list of functions having an optional chart= argument.

The chart map \(\varphi\) acting on a point is obtained by passing it as an input to the map:

sage: p = M.point((1+i, 2), chart=X); p
Point on the Complex 2-dimensional topological manifold M
sage: X(p)
(I + 1, 2)
sage: X(p) == p.coord(X)
True

See also

sage.manifolds.chart.RealChart for charts on topological manifolds over \(\RR\).

class sage.manifolds.chart.CoordChange(chart1, chart2, *transformations)

Bases: sage.structure.sage_object.SageObject

Transition map between two charts of a topological manifold.

Giving two coordinate charts \((U, \varphi)\) and \((V, \psi)\) on a topological manifold \(M\) of dimension \(n\) over a topological field \(K\), the transition map from \((U, \varphi)\) to \((V, \psi)\) is the map

\[\psi\circ\varphi^{-1}: \varphi(U\cap V) \subset K^n \rightarrow \psi(U\cap V) \subset K^n.\]

In other words, the transition map \(\psi \circ \varphi^{-1}\) expresses the coordinates \((y^1, \ldots, y^n)\) of \((V, \psi)\) in terms of the coordinates \((x^1, \ldots, x^n)\) of \((U, \varphi)\) on the open subset where the two charts intersect, i.e. on \(U \cap V\).

INPUT:

  • chart1 – chart \((U, \varphi)\)
  • chart2 – chart \((V, \psi)\)
  • transformations – tuple (or list) \((Y_1, \ldots, Y_2)\), where \(Y_i\) is the symbolic expression of the coordinate \(y^i\) in terms of the coordinates \((x^1, \ldots, x^n)\)

EXAMPLES:

Transition map on a 2-dimensional topological manifold:

sage: M = Manifold(2, 'M', structure='topological')
sage: X.<x,y> = M.chart()
sage: Y.<u,v> = M.chart()
sage: X_to_Y = X.transition_map(Y, [x+y, x-y])
sage: X_to_Y
Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v))
sage: type(X_to_Y)
<class 'sage.manifolds.chart.CoordChange'>
sage: X_to_Y.display()
u = x + y
v = x - y
disp()

Display of the coordinate transformation.

The output is either text-formatted (console mode) or LaTeX-formatted (notebook mode).

EXAMPLES:

From spherical coordinates to Cartesian ones in the plane:

sage: M = Manifold(2, 'R^2', structure='topological')
sage: U = M.open_subset('U') # the complement of the half line {y=0, x>= 0}
sage: c_cart.<x,y> = U.chart()
sage: c_spher.<r,ph> = U.chart(r'r:(0,+oo) ph:(0,2*pi):\phi')
sage: spher_to_cart = c_spher.transition_map(c_cart, [r*cos(ph), r*sin(ph)])
sage: spher_to_cart.display()
x = r*cos(ph)
y = r*sin(ph)
sage: latex(spher_to_cart.display())
\left\{\begin{array}{lcl} x & = & r \cos\left({\phi}\right) \\
 y & = & r \sin\left({\phi}\right) \end{array}\right.

A shortcut is disp():

sage: spher_to_cart.disp()
x = r*cos(ph)
y = r*sin(ph)
display()

Display of the coordinate transformation.

The output is either text-formatted (console mode) or LaTeX-formatted (notebook mode).

EXAMPLES:

From spherical coordinates to Cartesian ones in the plane:

sage: M = Manifold(2, 'R^2', structure='topological')
sage: U = M.open_subset('U') # the complement of the half line {y=0, x>= 0}
sage: c_cart.<x,y> = U.chart()
sage: c_spher.<r,ph> = U.chart(r'r:(0,+oo) ph:(0,2*pi):\phi')
sage: spher_to_cart = c_spher.transition_map(c_cart, [r*cos(ph), r*sin(ph)])
sage: spher_to_cart.display()
x = r*cos(ph)
y = r*sin(ph)
sage: latex(spher_to_cart.display())
\left\{\begin{array}{lcl} x & = & r \cos\left({\phi}\right) \\
 y & = & r \sin\left({\phi}\right) \end{array}\right.

A shortcut is disp():

sage: spher_to_cart.disp()
x = r*cos(ph)
y = r*sin(ph)
inverse()

Compute the inverse coordinate transformation.

OUTPUT:

  • an instance of CoordChange representing the inverse of the current coordinate transformation

EXAMPLES:

Inverse of a coordinate transformation corresponding to a rotation in the Cartesian plane:

sage: M = Manifold(2, 'M', structure='topological')
sage: c_xy.<x,y> = M.chart()
sage: c_uv.<u,v> = M.chart()
sage: phi = var('phi', domain='real')
sage: xy_to_uv = c_xy.transition_map(c_uv,
....:                                [cos(phi)*x + sin(phi)*y,
....:                                 -sin(phi)*x + cos(phi)*y])
sage: M.coord_changes()
{(Chart (M, (x, y)),
  Chart (M, (u, v))): Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v))}
sage: uv_to_xy = xy_to_uv.inverse(); uv_to_xy
Change of coordinates from Chart (M, (u, v)) to Chart (M, (x, y))
sage: uv_to_xy.display()
x = u*cos(phi) - v*sin(phi)
y = v*cos(phi) + u*sin(phi)
sage: M.coord_changes()  # random (dictionary output)
{(Chart (M, (u, v)),
  Chart (M, (x, y))): Change of coordinates from Chart (M, (u, v)) to Chart (M, (x, y)),
 (Chart (M, (x, y)),
  Chart (M, (u, v))): Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v))}
restrict(dom1, dom2=None)

Restriction to subsets.

INPUT:

  • dom1 – open subset of the domain of chart1
  • dom2 – (default: None) open subset of the domain of chart2; if None, dom1 is assumed

OUTPUT:

  • the transition map between the charts restricted to the specified subsets

EXAMPLES:

sage: M = Manifold(2, 'M', structure='topological')
sage: X.<x,y> = M.chart()
sage: Y.<u,v> = M.chart()
sage: X_to_Y = X.transition_map(Y, [x+y, x-y])
sage: U = M.open_subset('U', coord_def={X: x>0, Y: u+v>0})
sage: X_to_Y_U = X_to_Y.restrict(U); X_to_Y_U
Change of coordinates from Chart (U, (x, y)) to Chart (U, (u, v))
sage: X_to_Y_U.display()
u = x + y
v = x - y

The result is cached:

sage: X_to_Y.restrict(U) is X_to_Y_U
True
set_inverse(*transformations, **kwds)

Sets the inverse of the coordinate transformation.

This is useful when the automatic computation via inverse() fails.

INPUT:

  • transformations – the inverse transformations expressed as a list of the expressions of the “old” coordinates in terms of the “new” ones
  • kwds – keyword arguments: only verbose=True or verbose=False (default) are meaningful; it determines whether the provided transformations are checked to be indeed the inverse coordinate transformations

EXAMPLES:

From spherical coordinates to Cartesian ones in the plane:

sage: M = Manifold(2, 'R^2', structure='topological')
sage: U = M.open_subset('U') # the complement of the half line {y=0, x>= 0}
sage: c_cart.<x,y> = U.chart()
sage: c_spher.<r,ph> = U.chart(r'r:(0,+oo) ph:(0,2*pi):\phi')
sage: spher_to_cart = c_spher.transition_map(c_cart, [r*cos(ph), r*sin(ph)])
sage: spher_to_cart.set_inverse(sqrt(x^2+y^2), atan2(y,x))
sage: spher_to_cart.inverse()
Change of coordinates from Chart (U, (x, y)) to Chart (U, (r, ph))
sage: spher_to_cart.inverse().display()
r = sqrt(x^2 + y^2)
ph = arctan2(y, x)
sage: M.coord_changes()  # random (dictionary output)
{(Chart (U, (r, ph)),
  Chart (U, (x, y))): Change of coordinates from Chart (U, (r, ph)) to Chart (U, (x, y)),
 (Chart (U, (x, y)),
  Chart (U, (r, ph))): Change of coordinates from Chart (U, (x, y)) to Chart (U, (r, ph))}

Introducing a wrong inverse transformation (note the x^3 typo) is revealed by setting verbose to True:

sage: spher_to_cart.set_inverse(sqrt(x^3+y^2), atan2(y,x), verbose=True)
Check of the inverse coordinate transformation:
   r == sqrt(r*cos(ph)^3 + sin(ph)^2)*r
   ph == arctan2(r*sin(ph), r*cos(ph))
   x == sqrt(x^3 + y^2)*x/sqrt(x^2 + y^2)
   y == sqrt(x^3 + y^2)*y/sqrt(x^2 + y^2)
sage.manifolds.chart.RealChart

Chart on a topological manifold over \(\RR\).

Given a topological manifold \(M\) of dimension \(n\) over \(\RR\), a chart on \(M\) is a pair \((U,\varphi)\), where \(U\) is an open subset of \(M\) and \(\varphi : U \to V \subset \RR^n\) is a homeomorphism from \(U\) to an open subset \(V\) of \(\RR^n\).

The components \((x^1, \ldots, x^n)\) of \(\varphi\), defined by \(\varphi(p) = (x^1(p), \ldots, x^n(p))\in \RR^n\) for any point \(p \in U\), are called the coordinates of the chart \((U, \varphi)\).

INPUT:

  • domain – open subset \(U\) on which the chart is defined
  • coordinates – (default: '' (empty string)) string defining the coordinate symbols and ranges, see below
  • names – (default: None) unused argument, except if coordinates is not provided; it must then be a tuple containing the coordinate symbols (this is guaranteed if the shortcut operator <,> is used)
  • calc_method – (default: None) string defining the calculus method for computations involving coordinates of the chart; must be one of
    • 'SR': Sage’s default symbolic engine (Symbolic Ring)
    • 'sympy': SymPy
    • None: the default of CalculusMethod will be used

The string coordinates has the space ' ' as a separator and each item has at most three fields, separated by a colon (:):

  1. The coordinate symbol (a letter or a few letters).
  2. (optional) The interval \(I\) defining the coordinate range: if not provided, the coordinate is assumed to span all \(\RR\); otherwise \(I\) must be provided in the form (a,b) (or equivalently ]a,b[). The bounds a and b can be +/-Infinity, Inf, infinity, inf or oo. For singular coordinates, non-open intervals such as [a,b] and (a,b] (or equivalently ]a,b]) are allowed. Note that the interval declaration must not contain any whitespace.
  3. (optional) The LaTeX spelling of the coordinate; if not provided the coordinate symbol given in the first field will be used.

The order of the fields 2 and 3 does not matter and each of them can be omitted. If it contains any LaTeX expression, the string coordinates must be declared with the prefix ‘r’ (for “raw”) to allow for a proper treatment of LaTeX backslash characters (see examples below). If no interval range and no LaTeX spelling is to be set for any coordinate, the argument coordinates can be omitted when the shortcut operator <,> is used via Sage preparser (see examples below).

EXAMPLES:

Cartesian coordinates on \(\RR^3\):

sage: M = Manifold(3, 'R^3', r'\RR^3', structure='topological',
....:              start_index=1)
sage: c_cart = M.chart('x y z'); c_cart
Chart (R^3, (x, y, z))
sage: type(c_cart)
<class 'sage.manifolds.chart.RealChart'>

To have the coordinates accessible as global variables, one has to set:

sage: (x,y,z) = c_cart[:]

However, a shortcut is to use the declarator <x,y,z> in the left-hand side of the chart declaration (there is then no need to pass the string 'x y z' to chart()):

sage: M = Manifold(3, 'R^3', r'\RR^3', structure='topological',
....:              start_index=1)
sage: c_cart.<x,y,z> = M.chart(); c_cart
Chart (R^3, (x, y, z))

The coordinates are then immediately accessible:

sage: y
y
sage: y is c_cart[2]
True

Note that x, y, z declared in <x,y,z> are mere Python variable names and do not have to coincide with the coordinate symbols; for instance, one may write:

sage: M = Manifold(3, 'R^3', r'\RR^3', structure='topological', start_index=1)
sage: c_cart.<x1,y1,z1> = M.chart('x y z'); c_cart
Chart (R^3, (x, y, z))

Then y is not known as a global variable and the coordinate \(y\) is accessible only through the global variable y1:

sage: y1
y
sage: y1 is c_cart[2]
True

However, having the name of the Python variable coincide with the coordinate symbol is quite convenient; so it is recommended to declare:

sage: forget()   # for doctests only
sage: M = Manifold(3, 'R^3', r'\RR^3', structure='topological', start_index=1)
sage: c_cart.<x,y,z> = M.chart()

Spherical coordinates on the subset \(U\) of \(\RR^3\) that is the complement of the half-plane \(\{y=0, x \geq 0\}\):

sage: U = M.open_subset('U')
sage: c_spher.<r,th,ph> = U.chart(r'r:(0,+oo) th:(0,pi):\theta ph:(0,2*pi):\phi')
sage: c_spher
Chart (U, (r, th, ph))

Note the prefix ‘r’ for the string defining the coordinates in the arguments of chart.

Coordinates are Sage symbolic variables (see sage.symbolic.expression):

sage: type(th)
<type 'sage.symbolic.expression.Expression'>
sage: latex(th)
{\theta}
sage: assumptions(th)
[th is real, th > 0, th < pi]

Coordinate are also accessible by their indices:

sage: x1 = c_spher[1]; x2 = c_spher[2]; x3 = c_spher[3]
sage: [x1, x2, x3]
[r, th, ph]
sage: (x1, x2, x3) == (r, th, ph)
True

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

sage: c_cart[:]
(x, y, z)
sage: c_spher[:]
(r, th, ph)

Let us check that the declared coordinate ranges have been taken into account:

sage: c_cart.coord_range()
x: (-oo, +oo); y: (-oo, +oo); z: (-oo, +oo)
sage: c_spher.coord_range()
r: (0, +oo); th: (0, pi); ph: (0, 2*pi)
sage: bool(th>0 and th<pi)
True
sage: assumptions()  # list all current symbolic assumptions
[x is real, y is real, z is real, r is real, r > 0, th is real,
 th > 0, th < pi, ph is real, ph > 0, ph < 2*pi]

The coordinate ranges are used for simplifications:

sage: simplify(abs(r)) # r has been declared to lie in the interval (0,+oo)
r
sage: simplify(abs(x)) # no positive range has been declared for x
abs(x)

Each constructed chart is automatically added to the manifold’s user atlas:

sage: M.atlas()
[Chart (R^3, (x, y, z)), Chart (U, (r, th, ph))]

and to the atlas of its domain:

sage: U.atlas()
[Chart (U, (r, th, ph))]

Manifold subsets have a default chart, which, unless changed via the method set_default_chart(), is the first defined chart on the subset (or on a open subset of it):

sage: M.default_chart()
Chart (R^3, (x, y, z))
sage: U.default_chart()
Chart (U, (r, th, ph))

The default charts are not privileged charts on the manifold, but rather charts whose name can be skipped in the argument list of functions having an optional chart= argument.

The chart map \(\varphi\) acting on a point is obtained by means of the call operator, i.e. the operator ():

sage: p = M.point((1,0,-2)); p
Point on the 3-dimensional topological manifold R^3
sage: c_cart(p)
(1, 0, -2)
sage: c_cart(p) == p.coord(c_cart)
True
sage: q = M.point((2,pi/2,pi/3), chart=c_spher) # point defined by its spherical coordinates
sage: c_spher(q)
(2, 1/2*pi, 1/3*pi)
sage: c_spher(q) == q.coord(c_spher)
True
sage: a = U.point((1,pi/2,pi)) # the default coordinates on U are the spherical ones
sage: c_spher(a)
(1, 1/2*pi, pi)
sage: c_spher(a) == a.coord(c_spher)
True

Cartesian coordinates on \(U\) as an example of chart construction with coordinate restrictions: since \(U\) is the complement of the half-plane \(\{y = 0, x \geq 0\}\), we must have \(y \neq 0\) or \(x < 0\) on U. Accordingly, we set:

sage: c_cartU.<x,y,z> = U.chart()
sage: c_cartU.add_restrictions((y!=0, x<0))
sage: U.atlas()
[Chart (U, (r, th, ph)), Chart (U, (x, y, z))]
sage: M.atlas()
[Chart (R^3, (x, y, z)), Chart (U, (r, th, ph)), Chart (U, (x, y, z))]
sage: c_cartU.valid_coordinates(-1,0,2)
True
sage: c_cartU.valid_coordinates(1,0,2)
False
sage: c_cart.valid_coordinates(1,0,2)
True

Note that, as an example, the following would have meant \(y \neq 0\) and \(x < 0\):

c_cartU.add_restrictions([y!=0, x<0])

Chart grids can be drawn in 2D or 3D graphics thanks to the method plot().