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 ofTopologicalManifold
)coordinates
– (default:''
(empty string)) the string defining the coordinate symbols, see belownames
– (default:None
) unused argument, except ifcoordinates
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'
: SymPyNone
: the default ofCalculusMethod
will be used
The string
coordinates
has the space' '
as a separator and each item has at most two fields, separated by a colon (:
):- the coordinate symbol (a letter or a few letters);
- (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 argumentcoordinates
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'
tochart()
):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
andy
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 variabley1
: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 stringr'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))}
- an instance of
-
restrict
(dom1, dom2=None)¶ Restriction to subsets.
INPUT:
dom1
– open subset of the domain ofchart1
dom2
– (default:None
) open subset of the domain ofchart2
; ifNone
,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” oneskwds
– keyword arguments: onlyverbose=True
orverbose=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 settingverbose
toTrue
: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 definedcoordinates
– (default:''
(empty string)) string defining the coordinate symbols and ranges, see belownames
– (default:None
) unused argument, except ifcoordinates
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'
: SymPyNone
: the default ofCalculusMethod
will be used
The string
coordinates
has the space' '
as a separator and each item has at most three fields, separated by a colon (:
):- The coordinate symbol (a letter or a few letters).
- (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 boundsa
andb
can be+/-Infinity
,Inf
,infinity
,inf
oroo
. 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. - (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 argumentcoordinates
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'
tochart()
):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 variabley1
: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()
.