Coordinate Charts on Differentiable Manifolds - Manifolds

Skip to content
Back to top
View this page
Edit this page

# Coordinate Charts on Differentiable Manifolds

The class `DiffChart` implements coordinate charts on a differentiable manifold over a topological field \(K\) (in most applications, \(K = \RR\) or \(K = \CC\)).

The subclass `RealDiffChart` is devoted to the case \(K=\RR\), for which the concept of coordinate range is meaningful. Moreover, `RealDiffChart` is endowed with some plotting capabilities (cf. method `plot()`).

Transition maps between charts are implemented via the class `DiffCoordChange`.

AUTHORS:

- Eric Gourgoulhon, Michal Bejger (2013-2015) : initial version

REFERENCES:

- Chap. 1 of [Lee2013]

class sage.manifolds.differentiable.chart.DiffChart(domain, coordinates, calc_method=None, periods=None, coord_restrictions=None)

  Bases: `Chart`

  Chart on a differentiable manifold.

  Given a differentiable manifold \(M\) of dimension \(n\) over a topological field \(K\), a chart is a member \((U,\varphi)\) of the manifold’s differentiable atlas; \(U\) is then 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

  - `coordinates` – (default: ‘’ (empty string)) single string defining the coordinate symbols, with `' '` (whitespace) as a separator; each item has at most three fields, separated by a colon (`:`):

    1. the coordinate symbol (a letter or a few letters)

    2. (optional) the period of the coordinate if the coordinate is periodic; the period field must be written as `period=T`, where `T` is the period (see examples below)

    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 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’s backslash character (see examples below). If no period and no LaTeX spelling are to be set for any coordinate, the argument `coordinates` can be omitted when the shortcut operator `<,>` is used to declare the chart (see examples below).

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

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

  - `coord_restrictions` – additional restrictions on the coordinates. A restriction can be any symbolic equality or inequality involving the coordinates, such as `x > y` or `x^2 + y^2 != 0`. The items of the list (or set or frozenset) `coord_restrictions` are combined with the `and` operator; if some restrictions are to be combined with the `or` operator instead, they have to be passed as a tuple in some single item of the list (or set or frozenset) `coord_restrictions`. For example:

        coord_restrictions=[x > y, (x != 0, y != 0), z^2 < x]

    means `(x > y) and ((x != 0) or (y != 0)) and (z^2 < x)`. If the list `coord_restrictions` contains only one item, this item can be passed as such, i.e. writing `x > y` instead of the single element list `[x > y]`. If the chart variables have not been declared as variables yet, `coord_restrictions` must be `lambda`-quoted.

  EXAMPLES:

  A chart on a complex 2-dimensional differentiable manifold:

  Sage

      sage: M = Manifold(2, 'M', field='complex')
      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.differentiable.chart.DiffChart'>

  Python

      >>> from sage.all import *
      >>> M = Manifold(Integer(2), 'M', field='complex')
      >>> X = M.chart('x y'); X
      Chart (M, (x, y))
      >>> latex(X)
      \left(M,(x, y)\right)
      >>> type(X)
      <class 'sage.manifolds.differentiable.chart.DiffChart'>

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

  Sage

      sage: x,y = X[:]

  [Python]

      >>> from sage.all import *
      >>> 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

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

  Python

      >>> from sage.all import *
      >>> M = Manifold(Integer(2), 'M', field='complex')
      >>> X = M.chart(names=('x', 'y',)); (x, y,) = X._first_ngens(2); X
      Chart (M, (x, y))

  The coordinates are then immediately accessible:

  Sage

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

  [Python]

      >>> from sage.all import *
      >>> y
      y
      >>> x is X[Integer(0)] and y is X[Integer(1)]
      True

  The trick is performed by Sage preparser:

  Sage

      sage: preparse("X.<x,y> = M.chart()")
      "X = M.chart(names=('x', 'y',)); (x, y,) = X._first_ngens(2)"

  Python

      >>> from sage.all import *
      >>> preparse("X.<x,y> = M.chart()")
      "X = M.chart(names=('x', 'y',)); (x, y,) = X._first_ngens(2)"

  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

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

  [Python]

      >>> from sage.all import *
      >>> M = Manifold(Integer(2), 'M', field='complex')
      >>> X = M.chart('x y', names=('x1', 'y1',)); (x1, y1,) = X._first_ngens(2); 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

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

  Python

      >>> from sage.all import *
      >>> y1
      y
      >>> latex(y1)
      y
      >>> y1 is X[Integer(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

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

  [Python]

      >>> from sage.all import *
      >>> M = Manifold(Integer(2), 'M', field='complex')
      >>> X = M.chart(names=('x', 'y',)); (x, y,) = X._first_ngens(2)

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

  Sage

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

  Python

      >>> from sage.all import *
      >>> X.domain()
      2-dimensional complex manifold M

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

  Sage

      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 2-dimensional complex manifold M

  [Python]

      >>> from sage.all import *
      >>> U = M.open_subset('U')
      >>> Y = U.chart(r'z1:\zeta_1 z2:\zeta_2', names=('z1', 'z2',)); (z1, z2,) = Y._first_ngens(2); Y
      Chart (U, (z1, z2))
      >>> Y.domain()
      Open subset U of the 2-dimensional complex manifold M

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

  Sage

      sage: latex(z1)
      {\zeta_1}

  Python

      >>> from sage.all import *
      >>> 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.

  Periodic coordinates are declared through the keyword `period=` in the coordinate field:

  Sage

      sage: N = Manifold(2, 'N', field='complex')
      sage: XN.<Z1,Z2> = N.chart('Z1:period=1+2*I Z2')
      sage: XN.periods()
      (2*I + 1, None)

  [Python]

      >>> from sage.all import *
      >>> N = Manifold(Integer(2), 'N', field='complex')
      >>> XN = N.chart('Z1:period=1+2*I Z2', names=('Z1', 'Z2',)); (Z1, Z2,) = XN._first_ngens(2)
      >>> XN.periods()
      (2*I + 1, None)

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

  Sage

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

  Python

      >>> from sage.all import *
      >>> type(z1)
      <class 'sage.symbolic.expression.Expression'>

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

  Sage

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

  [Python]

      >>> from sage.all import *
      >>> Y[Integer(0)], Y[Integer(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

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

  Python

      >>> from sage.all import *
      >>> M1 = Manifold(Integer(2), 'M_1', field='complex', start_index=Integer(1))
      >>> Z = M1.chart(names=('u', 'v',)); (u, v,) = Z._first_ngens(2)
      >>> Z[Integer(1)], Z[Integer(2)]
      (u, v)

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

  Sage

      sage: Y[:]
      (z1, z2)

  [Python]

      >>> from sage.all import *
      >>> Y[:]
      (z1, z2)

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

  Sage

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

  Python

      >>> from sage.all import *
      >>> M.atlas()
      [Chart (M, (x, y)), Chart (U, (z1, z2))]

  and to the atlas of the chart’s domain:

  Sage

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

  [Python]

      >>> from sage.all import *
      >>> 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

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

  Python

      >>> from sage.all import *
      >>> M.default_chart()
      Chart (M, (x, y))
      >>> 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 action of the chart map \(\varphi\) on a point is obtained by means of the call operator, i.e. the operator `()`:

  Sage

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

  [Python]

      >>> from sage.all import *
      >>> p = M.point((Integer(1)+i, Integer(2)), chart=X); p
      Point on the 2-dimensional complex manifold M
      >>> X(p)
      (I + 1, 2)
      >>> X(p) == p.coord(X)
      True

  A vector frame is naturally associated to each chart:

  Sage

      sage: X.frame()
      Coordinate frame (M, (∂/∂x,∂/∂y))
      sage: Y.frame()
      Coordinate frame (U, (∂/∂z1,∂/∂z2))

  Python

      >>> from sage.all import *
      >>> X.frame()
      Coordinate frame (M, (∂/∂x,∂/∂y))
      >>> Y.frame()
      Coordinate frame (U, (∂/∂z1,∂/∂z2))

  as well as a dual frame (basis of 1-forms):

  Sage

      sage: X.coframe()
      Coordinate coframe (M, (dx,dy))
      sage: Y.coframe()
      Coordinate coframe (U, (dz1,dz2))

  [Python]

      >>> from sage.all import *
      >>> X.coframe()
      Coordinate coframe (M, (dx,dy))
      >>> Y.coframe()
      Coordinate coframe (U, (dz1,dz2))

  See also

  `RealDiffChart` for charts on differentiable manifolds over \(\RR\).

  coframe()

    Return the coframe (basis of coordinate differentials) associated with `self`.

    OUTPUT:

    - a `CoordCoFrame` representing the coframe

    EXAMPLES:

    Coordinate coframe associated with some chart on a 2-dimensional manifold:

    Sage

        sage: M = Manifold(2, 'M')
        sage: c_xy.<x,y> = M.chart()
        sage: c_xy.coframe()
        Coordinate coframe (M, (dx,dy))
        sage: type(c_xy.coframe())
        <class 'sage.manifolds.differentiable.vectorframe.CoordCoFrame_with_category'>

    Python

        >>> from sage.all import *
        >>> M = Manifold(Integer(2), 'M')
        >>> c_xy = M.chart(names=('x', 'y',)); (x, y,) = c_xy._first_ngens(2)
        >>> c_xy.coframe()
        Coordinate coframe (M, (dx,dy))
        >>> type(c_xy.coframe())
        <class 'sage.manifolds.differentiable.vectorframe.CoordCoFrame_with_category'>

    Check that `c_xy.coframe()` is indeed the coordinate coframe associated with the coordinates \((x, y)\):

    Sage

        sage: dx = c_xy.coframe()[0] ; dx
        1-form dx on the 2-dimensional differentiable manifold M
        sage: dy = c_xy.coframe()[1] ; dy
        1-form dy on the 2-dimensional differentiable manifold M
        sage: ex = c_xy.frame()[0] ; ex
        Vector field ∂/∂x on the 2-dimensional differentiable manifold M
        sage: ey = c_xy.frame()[1] ; ey
        Vector field ∂/∂y on the 2-dimensional differentiable manifold M
        sage: dx(ex).display()
        dx(∂/∂x): M → ℝ
           (x, y) ↦ 1
        sage: dx(ey).display()
        dx(∂/∂y): M → ℝ
           (x, y) ↦ 0
        sage: dy(ex).display()
        dy(∂/∂x): M → ℝ
           (x, y) ↦ 0
        sage: dy(ey).display()
        dy(∂/∂y): M → ℝ
           (x, y) ↦ 1

    [Python]

        >>> from sage.all import *
        >>> dx = c_xy.coframe()[Integer(0)] ; dx
        1-form dx on the 2-dimensional differentiable manifold M
        >>> dy = c_xy.coframe()[Integer(1)] ; dy
        1-form dy on the 2-dimensional differentiable manifold M
        >>> ex = c_xy.frame()[Integer(0)] ; ex
        Vector field ∂/∂x on the 2-dimensional differentiable manifold M
        >>> ey = c_xy.frame()[Integer(1)] ; ey
        Vector field ∂/∂y on the 2-dimensional differentiable manifold M
        >>> dx(ex).display()
        dx(∂/∂x): M → ℝ
           (x, y) ↦ 1
        >>> dx(ey).display()
        dx(∂/∂y): M → ℝ
           (x, y) ↦ 0
        >>> dy(ex).display()
        dy(∂/∂x): M → ℝ
           (x, y) ↦ 0
        >>> dy(ey).display()
        dy(∂/∂y): M → ℝ
           (x, y) ↦ 1

  frame()

    Return the vector frame (coordinate frame) associated with `self`.

    OUTPUT:

    - a `CoordFrame` representing the coordinate frame

    EXAMPLES:

    Coordinate frame associated with some chart on a 2-dimensional manifold:

    Sage

        sage: M = Manifold(2, 'M')
        sage: c_xy.<x,y> = M.chart()
        sage: c_xy.frame()
        Coordinate frame (M, (∂/∂x,∂/∂y))
        sage: type(c_xy.frame())
        <class 'sage.manifolds.differentiable.vectorframe.CoordFrame_with_category'>

    Python

        >>> from sage.all import *
        >>> M = Manifold(Integer(2), 'M')
        >>> c_xy = M.chart(names=('x', 'y',)); (x, y,) = c_xy._first_ngens(2)
        >>> c_xy.frame()
        Coordinate frame (M, (∂/∂x,∂/∂y))
        >>> type(c_xy.frame())
        <class 'sage.manifolds.differentiable.vectorframe.CoordFrame_with_category'>

    Check that `c_xy.frame()` is indeed the coordinate frame associated with the coordinates \((x,y)\):

    Sage

        sage: ex = c_xy.frame()[0] ; ex
        Vector field ∂/∂x on the 2-dimensional differentiable manifold M
        sage: ey = c_xy.frame()[1] ; ey
        Vector field ∂/∂y on the 2-dimensional differentiable manifold M
        sage: ex(M.scalar_field(x)).display()
        1: M → ℝ
           (x, y) ↦ 1
        sage: ex(M.scalar_field(y)).display()
        zero: M → ℝ
           (x, y) ↦ 0
        sage: ey(M.scalar_field(x)).display()
        zero: M → ℝ
           (x, y) ↦ 0
        sage: ey(M.scalar_field(y)).display()
        1: M → ℝ
           (x, y) ↦ 1

    [Python]

        >>> from sage.all import *
        >>> ex = c_xy.frame()[Integer(0)] ; ex
        Vector field ∂/∂x on the 2-dimensional differentiable manifold M
        >>> ey = c_xy.frame()[Integer(1)] ; ey
        Vector field ∂/∂y on the 2-dimensional differentiable manifold M
        >>> ex(M.scalar_field(x)).display()
        1: M → ℝ
           (x, y) ↦ 1
        >>> ex(M.scalar_field(y)).display()
        zero: M → ℝ
           (x, y) ↦ 0
        >>> ey(M.scalar_field(x)).display()
        zero: M → ℝ
           (x, y) ↦ 0
        >>> ey(M.scalar_field(y)).display()
        1: M → ℝ
           (x, y) ↦ 1

  restrict(subset, restrictions=None)

    Return the restriction of `self` to some subset.

    If the current chart is \((U, \varphi)\), a restriction (or subchart) is a chart \((V, \psi)\) such that \(V \subset U\) and \(\psi = \varphi |_V\).

    If such subchart has not been defined yet, it is constructed here.

    The coordinates of the subchart bare the same names as the coordinates of the original chart.

    INPUT:

    - `subset` – open subset \(V\) of the chart domain \(U\)

    - `restrictions` – (default: `None`) list of coordinate restrictions defining the subset \(V\)

    A restriction can be any symbolic equality or inequality involving the coordinates, such as `x > y` or `x^2 + y^2 != 0`. The items of the list `restrictions` are combined with the `and` operator; if some restrictions are to be combined with the `or` operator instead, they have to be passed as a tuple in some single item of the list `restrictions`. For example:

        restrictions = [x > y, (x != 0, y != 0), z^2 < x]

    means `(x > y) and ((x != 0) or (y != 0)) and (z^2 < x)`. If the list `restrictions` contains only one item, this item can be passed as such, i.e. writing `x > y` instead of the single element list `[x > y]`.

    OUTPUT:

    - a `DiffChart` \((V, \psi)\)

    EXAMPLES:

    Coordinates on the unit open ball of \(\CC^2\) as a subchart of the global coordinates of \(\CC^2\):

    Sage

        sage: M = Manifold(2, 'C^2', field='complex')
        sage: X.<z1, z2> = M.chart()
        sage: B = M.open_subset('B')
        sage: X_B = X.restrict(B, abs(z1)^2 + abs(z2)^2 < 1); X_B
        Chart (B, (z1, z2))

    Python

        >>> from sage.all import *
        >>> M = Manifold(Integer(2), 'C^2', field='complex')
        >>> X = M.chart(names=('z1', 'z2',)); (z1, z2,) = X._first_ngens(2)
        >>> B = M.open_subset('B')
        >>> X_B = X.restrict(B, abs(z1)**Integer(2) + abs(z2)**Integer(2) < Integer(1)); X_B
        Chart (B, (z1, z2))

  symbolic_velocities(left='D', right=None)

    Return a list of symbolic variables ready to be used by the user as the derivatives of the coordinate functions with respect to a curve parameter (i.e. the velocities along the curve). It may actually serve to denote anything else than velocities, with a name including the coordinate functions. The choice of strings provided as ‘left’ and ‘right’ arguments is not entirely free since it must comply with Python prescriptions.

    INPUT:

    - `left` – (default: `D`) string to concatenate to the left of each coordinate functions of the chart

    - `right` – (default: `None`) string to concatenate to the right of each coordinate functions of the chart

    OUTPUT: list of symbolic expressions with the desired names

    EXAMPLES:

    Symbolic derivatives of the Cartesian coordinates of the 3-dimensional Euclidean space:

    Sage

        sage: R3 = Manifold(3, 'R3', start_index=1)
        sage: cart.<X,Y,Z> = R3.chart()
        sage: D = cart.symbolic_velocities(); D
        [DX, DY, DZ]
        sage: D = cart.symbolic_velocities(left='d', right='/dt'); D
        Traceback (most recent call last):
        ...
        ValueError: The name "dX/dt" is not a valid Python
         identifier.
        sage: D = cart.symbolic_velocities(left='d', right='_dt'); D
        [dX_dt, dY_dt, dZ_dt]
        sage: D = cart.symbolic_velocities(left='', right="'"); D
        Traceback (most recent call last):
        ...
        ValueError: The name "X'" is not a valid Python
         identifier.
        sage: D = cart.symbolic_velocities(left='', right='_dot'); D
        [X_dot, Y_dot, Z_dot]
        sage: R.<t> = manifolds.RealLine()
        sage: canon_chart = R.default_chart()
        sage: D = canon_chart.symbolic_velocities() ; D
        [Dt]

    Python

        >>> from sage.all import *
        >>> R3 = Manifold(Integer(3), 'R3', start_index=Integer(1))
        >>> cart = R3.chart(names=('X', 'Y', 'Z',)); (X, Y, Z,) = cart._first_ngens(3)
        >>> D = cart.symbolic_velocities(); D
        [DX, DY, DZ]
        >>> D = cart.symbolic_velocities(left='d', right='/dt'); D
        Traceback (most recent call last):
        ...
        ValueError: The name "dX/dt" is not a valid Python
         identifier.
        >>> D = cart.symbolic_velocities(left='d', right='_dt'); D
        [dX_dt, dY_dt, dZ_dt]
        >>> D = cart.symbolic_velocities(left='', right="'"); D
        Traceback (most recent call last):
        ...
        ValueError: The name "X'" is not a valid Python
         identifier.
        >>> D = cart.symbolic_velocities(left='', right='_dot'); D
        [X_dot, Y_dot, Z_dot]
        >>> R = manifolds.RealLine(names=('t',)); (t,) = R._first_ngens(1)
        >>> canon_chart = R.default_chart()
        >>> D = canon_chart.symbolic_velocities() ; D
        [Dt]

  transition_map(other, transformations, intersection_name=None, restrictions1=None, restrictions2=None)

    Construct the transition map between the current chart, \((U,\varphi)\) say, and another one, \((V,\psi)\) say.

    If \(n\) is the manifold’s dimension, the transition map is the map

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

    where \(K\) is the manifold’s base field. In other words, the transition map 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\).

    By definition, the transition map \(\psi\circ\varphi^{-1}\) must be of class \(C^k\), where \(k\) is the degree of differentiability of the manifold (cf. `diff_degree()`).

    INPUT:

    - `other` – the 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)\)

    - `intersection_name` – (default: `None`) name to be given to the subset \(U\cap V\) if the latter differs from \(U\) or \(V\)

    - `restrictions1` – (default: `None`) list of conditions on the coordinates of the current chart that define \(U\cap V\) if the latter differs from \(U\). `restrictions1` must be a list of of symbolic equalities or inequalities involving the coordinates, such as x>y or x^2+y^2 != 0. The items of the list `restrictions1` are combined with the `and` operator; if some restrictions are to be combined with the `or` operator instead, they have to be passed as a tuple in some single item of the list `restrictions1`. For example, `restrictions1` = [x>y, (x!=0, y!=0), z^2<x] means (x>y) and ((x!=0) or (y!=0)) and (z^2<x). If the list `restrictions1` contains only one item, this item can be passed as such, i.e. writing x>y instead of the single-element list [x>y].

    - `restrictions2` – (default: `None`) list of conditions on the coordinates of the chart \((V,\psi)\) that define \(U\cap V\) if the latter differs from \(V\) (see `restrictions1` for the syntax)

    OUTPUT:

    - The transition map \(\psi\circ\varphi^{-1}\) defined on \(U\cap V\), as an instance of `DiffCoordChange`.

    EXAMPLES:

    Transition map between two stereographic charts on the circle \(S^1\):

    Sage

        sage: M = Manifold(1, 'S^1')
        sage: U = M.open_subset('U') # Complement of the North pole
        sage: cU.<x> = U.chart() # Stereographic chart from the North pole
        sage: V = M.open_subset('V') # Complement of the South pole
        sage: cV.<y> = V.chart() # Stereographic chart from the South pole
        sage: M.declare_union(U,V)   # S^1 is the union of U and V
        sage: trans = cU.transition_map(cV, 1/x, intersection_name='W',
        ....:                           restrictions1= x!=0, restrictions2 = y!=0)
        sage: trans
        Change of coordinates from Chart (W, (x,)) to Chart (W, (y,))
        sage: trans.display()
        y = 1/x

    Python

        >>> from sage.all import *
        >>> M = Manifold(Integer(1), 'S^1')
        >>> U = M.open_subset('U') # Complement of the North pole
        >>> cU = U.chart(names=('x',)); (x,) = cU._first_ngens(1)# Stereographic chart from the North pole
        >>> V = M.open_subset('V') # Complement of the South pole
        >>> cV = V.chart(names=('y',)); (y,) = cV._first_ngens(1)# Stereographic chart from the South pole
        >>> M.declare_union(U,V)   # S^1 is the union of U and V
        >>> trans = cU.transition_map(cV, Integer(1)/x, intersection_name='W',
        ...                           restrictions1= x!=Integer(0), restrictions2 = y!=Integer(0))
        >>> trans
        Change of coordinates from Chart (W, (x,)) to Chart (W, (y,))
        >>> trans.display()
        y = 1/x

    The subset \(W\), intersection of \(U\) and \(V\), has been created by `transition_map()`:

    Sage

        sage: F = M.subset_family(); F
        Set {S^1, U, V, W} of open subsets of the 1-dimensional differentiable manifold S^1
        sage: W = F['W']
        sage: W is U.intersection(V)
        True
        sage: M.atlas()
        [Chart (U, (x,)), Chart (V, (y,)), Chart (W, (x,)), Chart (W, (y,))]

    [Python]

        >>> from sage.all import *
        >>> F = M.subset_family(); F
        Set {S^1, U, V, W} of open subsets of the 1-dimensional differentiable manifold S^1
        >>> W = F['W']
        >>> W is U.intersection(V)
        True
        >>> M.atlas()
        [Chart (U, (x,)), Chart (V, (y,)), Chart (W, (x,)), Chart (W, (y,))]

    Transition map between the polar chart and the Cartesian one on \(\RR^2\):

    Sage

        sage: M = Manifold(2, 'R^2')
        sage: c_cart.<x,y> = M.chart()
        sage: U = M.open_subset('U') # the complement of the half line {y=0, x >= 0}
        sage: c_spher.<r,phi> = U.chart(r'r:(0,+oo) phi:(0,2*pi):\phi')
        sage: trans = c_spher.transition_map(c_cart, (r*cos(phi), r*sin(phi)),
        ....:                                restrictions2=(y!=0, x<0))
        sage: trans
        Change of coordinates from Chart (U, (r, phi)) to Chart (U, (x, y))
        sage: trans.display()
        x = r*cos(phi)
        y = r*sin(phi)

    Python

        >>> from sage.all import *
        >>> M = Manifold(Integer(2), 'R^2')
        >>> c_cart = M.chart(names=('x', 'y',)); (x, y,) = c_cart._first_ngens(2)
        >>> U = M.open_subset('U') # the complement of the half line {y=0, x >= 0}
        >>> c_spher = U.chart(r'r:(0,+oo) phi:(0,2*pi):\phi', names=('r', 'phi',)); (r, phi,) = c_spher._first_ngens(2)
        >>> trans = c_spher.transition_map(c_cart, (r*cos(phi), r*sin(phi)),
        ...                                restrictions2=(y!=Integer(0), x<Integer(0)))
        >>> trans
        Change of coordinates from Chart (U, (r, phi)) to Chart (U, (x, y))
        >>> trans.display()
        x = r*cos(phi)
        y = r*sin(phi)

    In this case, no new subset has been created since \(U\cap M = U\):

    Sage

        sage: M.subset_family()
        Set {R^2, U} of open subsets of the 2-dimensional differentiable manifold R^2

    [Python]

        >>> from sage.all import *
        >>> M.subset_family()
        Set {R^2, U} of open subsets of the 2-dimensional differentiable manifold R^2

    but a new chart has been created: \((U, (x, y))\):

    Sage

        sage: M.atlas()
        [Chart (R^2, (x, y)), Chart (U, (r, phi)), Chart (U, (x, y))]

    Python

        >>> from sage.all import *
        >>> M.atlas()
        [Chart (R^2, (x, y)), Chart (U, (r, phi)), Chart (U, (x, y))]

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

  Bases: `CoordChange`

  Transition map between two charts of a differentiable manifold.

  Giving two coordinate charts \((U,\varphi)\) and \((V,\psi)\) on a differentiable 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\).

  By definition, the transition map \(\psi\circ\varphi^{-1}\) must be of class \(C^k\), where \(k\) is the degree of differentiability of the manifold (cf. `diff_degree()`).

  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 differentiable manifold:

  Sage

      sage: M = Manifold(2, 'M')
      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.differentiable.chart.DiffCoordChange'>
      sage: X_to_Y.display()
      u = x + y
      v = x - y

  Python

      >>> from sage.all import *
      >>> M = Manifold(Integer(2), 'M')
      >>> X = M.chart(names=('x', 'y',)); (x, y,) = X._first_ngens(2)
      >>> Y = M.chart(names=('u', 'v',)); (u, v,) = Y._first_ngens(2)
      >>> X_to_Y = X.transition_map(Y, [x+y, x-y])
      >>> X_to_Y
      Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v))
      >>> type(X_to_Y)
      <class 'sage.manifolds.differentiable.chart.DiffCoordChange'>
      >>> X_to_Y.display()
      u = x + y
      v = x - y

  jacobian()

    Return the Jacobian matrix of `self`.

    If `self` corresponds to the change of coordinates

    \[y^i = Y^i(x^1,\ldots,x^n)\qquad 1\leq i \leq n\]

    the Jacobian matrix \(J\) is given by

    \[J_{ij} = \frac{\partial Y^i}{\partial x^j}\]

    where \(i\) is the row index and \(j\) the column one.

    OUTPUT:

    - Jacobian matrix \(J\), the elements \(J_{ij}\) of which being coordinate functions (cf. `ChartFunction`)

    EXAMPLES:

    Jacobian matrix of a 2-dimensional transition map:

    Sage

        sage: M = Manifold(2, 'M')
        sage: X.<x,y> = M.chart()
        sage: Y.<u,v> = M.chart()
        sage: X_to_Y = X.transition_map(Y, [x+y^2, 3*x-y])
        sage: X_to_Y.jacobian()
        [  1 2*y]
        [  3  -1]

    Python

        >>> from sage.all import *
        >>> M = Manifold(Integer(2), 'M')
        >>> X = M.chart(names=('x', 'y',)); (x, y,) = X._first_ngens(2)
        >>> Y = M.chart(names=('u', 'v',)); (u, v,) = Y._first_ngens(2)
        >>> X_to_Y = X.transition_map(Y, [x+y**Integer(2), Integer(3)*x-y])
        >>> X_to_Y.jacobian()
        [  1 2*y]
        [  3  -1]

    Each element of the Jacobian matrix is a coordinate function:

    Sage

        sage: parent(X_to_Y.jacobian()[0,0])
        Ring of chart functions on Chart (M, (x, y))

    [Python]

        >>> from sage.all import *
        >>> parent(X_to_Y.jacobian()[Integer(0),Integer(0)])
        Ring of chart functions on Chart (M, (x, y))

  jacobian_det()

    Return the Jacobian determinant of `self`.

    The Jacobian determinant is the determinant of the Jacobian matrix (see `jacobian()`).

    OUTPUT:

    - determinant of the Jacobian matrix \(J\) as a coordinate function (cf. `ChartFunction`)

    EXAMPLES:

    Jacobian determinant of a 2-dimensional transition map:

    Sage

        sage: M = Manifold(2, 'M')
        sage: X.<x,y> = M.chart()
        sage: Y.<u,v> = M.chart()
        sage: X_to_Y = X.transition_map(Y, [x+y^2, 3*x-y])
        sage: X_to_Y.jacobian_det()
        -6*y - 1
        sage: X_to_Y.jacobian_det() == det(X_to_Y.jacobian())
        True

    Python

        >>> from sage.all import *
        >>> M = Manifold(Integer(2), 'M')
        >>> X = M.chart(names=('x', 'y',)); (x, y,) = X._first_ngens(2)
        >>> Y = M.chart(names=('u', 'v',)); (u, v,) = Y._first_ngens(2)
        >>> X_to_Y = X.transition_map(Y, [x+y**Integer(2), Integer(3)*x-y])
        >>> X_to_Y.jacobian_det()
        -6*y - 1
        >>> X_to_Y.jacobian_det() == det(X_to_Y.jacobian())
        True

    The Jacobian determinant is a coordinate function:

    Sage

        sage: parent(X_to_Y.jacobian_det())
        Ring of chart functions on Chart (M, (x, y))

    [Python]

        >>> from sage.all import *
        >>> parent(X_to_Y.jacobian_det())
        Ring of chart functions on Chart (M, (x, y))

class sage.manifolds.differentiable.chart.RealDiffChart(domain, coordinates, calc_method=None, bounds=None, periods=None, coord_restrictions=None)

  Bases: `DiffChart`, `RealChart`

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

  Given a differentiable manifold \(M\) of dimension \(n\) over \(\RR\), a chart is a member \((U,\varphi)\) of the manifold’s differentiable atlas; \(U\) is then an open subset of \(M\) and \(\varphi: U \rightarrow 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)) single string defining the coordinate symbols, with `' '` (whitespace) as a separator; each item has at most four 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) indicator of the periodic character of the coordinate, either as `period=T`, where `T` is the period, or as the keyword `periodic` (the value of the period is then deduced from the interval \(I\) declared in field 2; see examples below)

    4. (optional) the LaTeX spelling of the coordinate; if not provided the coordinate symbol given in the first field will be used

    The order of fields 2 to 4 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’s backslash character (see examples below). If interval range, no period and no LaTeX spelling are to be set for any coordinate, the argument `coordinates` can be omitted when the shortcut operator `<,>` is used to declare the chart (see examples below).

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

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

  - `coord_restrictions` – additional restrictions on the coordinates. A restriction can be any symbolic equality or inequality involving the coordinates, such as `x > y` or `x^2 + y^2 != 0`. The items of the list (or set or frozenset) `coord_restrictions` are combined with the `and` operator; if some restrictions are to be combined with the `or` operator instead, they have to be passed as a tuple in some single item of the list (or set or frozenset) `coord_restrictions`. For example:

        coord_restrictions=[x > y, (x != 0, y != 0), z^2 < x]

    means `(x > y) and ((x != 0) or (y != 0)) and (z^2 < x)`. If the list `coord_restrictions` contains only one item, this item can be passed as such, i.e. writing `x > y` instead of the single element list `[x > y]`. If the chart variables have not been declared as variables yet, `coord_restrictions` must be `lambda`-quoted.

  EXAMPLES:

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

  Sage

      sage: M = Manifold(3, 'R^3', r'\RR^3', 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.differentiable.chart.RealDiffChart'>

  Python

      >>> from sage.all import *
      >>> M = Manifold(Integer(3), 'R^3', r'\RR^3', start_index=Integer(1))
      >>> c_cart = M.chart('x y z'); c_cart
      Chart (R^3, (x, y, z))
      >>> type(c_cart)
      <class 'sage.manifolds.differentiable.chart.RealDiffChart'>

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

  Sage

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

  [Python]

      >>> from sage.all import *
      >>> (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

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

  Python

      >>> from sage.all import *
      >>> M = Manifold(Integer(3), 'R^3', r'\RR^3', start_index=Integer(1))
      >>> c_cart = M.chart(names=('x', 'y', 'z',)); (x, y, z,) = c_cart._first_ngens(3); c_cart
      Chart (R^3, (x, y, z))

  The coordinates are then immediately accessible:

  Sage

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

  [Python]

      >>> from sage.all import *
      >>> y
      y
      >>> y is c_cart[Integer(2)]
      True

  The trick is performed by Sage preparser:

  Sage

      sage: preparse("c_cart.<x,y,z> = M.chart()")
      "c_cart = M.chart(names=('x', 'y', 'z',)); (x, y, z,) = c_cart._first_ngens(3)"

  Python

      >>> from sage.all import *
      >>> preparse("c_cart.<x,y,z> = M.chart()")
      "c_cart = M.chart(names=('x', 'y', 'z',)); (x, y, z,) = c_cart._first_ngens(3)"

  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

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

  [Python]

      >>> from sage.all import *
      >>> M = Manifold(Integer(3), 'R^3', r'\RR^3', start_index=Integer(1))
      >>> c_cart = M.chart('x y z', names=('x1', 'y1', 'z1',)); (x1, y1, z1,) = c_cart._first_ngens(3); 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

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

  Python

      >>> from sage.all import *
      >>> y1
      y
      >>> y1 is c_cart[Integer(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

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

  [Python]

      >>> from sage.all import *
      >>> forget()   # for doctests only
      >>> M = Manifold(Integer(3), 'R^3', r'\RR^3', start_index=Integer(1))
      >>> c_cart = M.chart(names=('x', 'y', 'z',)); (x, y, z,) = c_cart._first_ngens(3)

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

  Sage

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

  Python

      >>> from sage.all import *
      >>> U = M.open_subset('U')
      >>> c_spher = U.chart(r'r:(0,+oo) th:(0,pi):\theta ph:(0,2*pi):\phi', names=('r', 'th', 'ph',)); (r, th, ph,) = c_spher._first_ngens(3)
      >>> 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

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

  [Python]

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

  Coordinate are also accessible by their indices:

  Sage

      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

  Python

      >>> from sage.all import *
      >>> x1 = c_spher[Integer(1)]; x2 = c_spher[Integer(2)]; x3 = c_spher[Integer(3)]
      >>> [x1, x2, x3]
      [r, th, ph]
      >>> (x1, x2, x3) == (r, th, ph)
      True

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

  Sage

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

  [Python]

      >>> from sage.all import *
      >>> c_cart[:]
      (x, y, z)
      >>> c_spher[:]
      (r, th, ph)

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

  Sage

      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]

  Python

      >>> from sage.all import *
      >>> c_cart.coord_range()
      x: (-oo, +oo); y: (-oo, +oo); z: (-oo, +oo)
      >>> c_spher.coord_range()
      r: (0, +oo); th: (0, pi); ph: (0, 2*pi)
      >>> bool(th>Integer(0) and th<pi)
      True
      >>> 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

      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)

  [Python]

      >>> from sage.all import *
      >>> simplify(abs(r)) # r has been declared to lie in the interval (0,+oo)
      r
      >>> simplify(abs(x)) # no positive range has been declared for x
      abs(x)

  A coordinate can be declared periodic by adding the keyword `periodic` to its range:

  Sage

      sage: V = M.open_subset('V')
      sage: c_spher1.<r,th,ph1> = \
      ....: V.chart(r'r:(0,+oo) th:(0,pi):\theta ph1:(0,2*pi):periodic:\phi_1')
      sage: c_spher1.periods()
      (None, None, 2*pi)
      sage: c_spher1.coord_range()
      r: (0, +oo); th: (0, pi); ph1: [0, 2*pi] (periodic)

  Python

      >>> from sage.all import *
      >>> V = M.open_subset('V')
      >>> c_spher1 = V.chart(r'r:(0,+oo) th:(0,pi):\theta ph1:(0,2*pi):periodic:\phi_1', names=('r', 'th', 'ph1',)); (r, th, ph1,) = c_spher1._first_ngens(3)
      >>> c_spher1.periods()
      (None, None, 2*pi)
      >>> c_spher1.coord_range()
      r: (0, +oo); th: (0, pi); ph1: [0, 2*pi] (periodic)

  It is equivalent to give the period as `period=2*pi`, skipping the coordinate range:

  Sage

      sage: c_spher2.<r,th,ph2> = \
      ....: V.chart(r'r:(0,+oo) th:(0,pi):\theta ph2:period=2*pi:\phi_2')
      sage: c_spher2.periods()
      (None, None, 2*pi)
      sage: c_spher2.coord_range()
      r: (0, +oo); th: (0, pi); ph2: [0, 2*pi] (periodic)

  [Python]

      >>> from sage.all import *
      >>> c_spher2 = V.chart(r'r:(0,+oo) th:(0,pi):\theta ph2:period=2*pi:\phi_2', names=('r', 'th', 'ph2',)); (r, th, ph2,) = c_spher2._first_ngens(3)
      >>> c_spher2.periods()
      (None, None, 2*pi)
      >>> c_spher2.coord_range()
      r: (0, +oo); th: (0, pi); ph2: [0, 2*pi] (periodic)

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

  Sage

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

  Python

      >>> from sage.all import *
      >>> M.atlas()
      [Chart (R^3, (x, y, z)), Chart (U, (r, th, ph)),
       Chart (V, (r, th, ph1)), Chart (V, (r, th, ph2))]

  and to the atlas of its domain:

  Sage

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

  [Python]

      >>> from sage.all import *
      >>> 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

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

  Python

      >>> from sage.all import *
      >>> M.default_chart()
      Chart (R^3, (x, y, z))
      >>> 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 action of the chart map \(\varphi\) on a point is obtained by means of the call operator, i.e. the operator `()`:

  Sage

      sage: p = M.point((1,0,-2)); p
      Point on the 3-dimensional differentiable 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

  [Python]

      >>> from sage.all import *
      >>> p = M.point((Integer(1),Integer(0),-Integer(2))); p
      Point on the 3-dimensional differentiable manifold R^3
      >>> c_cart(p)
      (1, 0, -2)
      >>> c_cart(p) == p.coord(c_cart)
      True
      >>> q = M.point((Integer(2),pi/Integer(2),pi/Integer(3)), chart=c_spher) # point defined by its spherical coordinates
      >>> c_spher(q)
      (2, 1/2*pi, 1/3*pi)
      >>> c_spher(q) == q.coord(c_spher)
      True
      >>> a = U.point((Integer(1),pi/Integer(2),pi)) # the default coordinates on U are the spherical ones
      >>> c_spher(a)
      (1, 1/2*pi, pi)
      >>> 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\not=0\) or \(x<0\) on U. Accordingly, we set:

  Sage

      sage: c_cartU.<x,y,z> = U.chart(coord_restrictions=lambda x,y,z: (y!=0, x<0))
      ....:    # the tuple (y!=0, x<0) means y!=0 or x<0
      ....:    #           [y!=0, x<0] would have meant y!=0 AND 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 (V, (r, th, ph1)), Chart (V, (r, th, ph2)),
       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

  Python

      >>> from sage.all import *
      >>> c_cartU = U.chart(coord_restrictions=lambda x,y,z: (y!=Integer(0), x<Integer(0)), names=('x', 'y', 'z',)); (x, y, z,) = c_cartU._first_ngens(3)
      ...    # the tuple (y!=0, x<0) means y!=0 or x<0
      ...    #           [y!=0, x<0] would have meant y!=0 AND x<0
      >>> U.atlas()
      [Chart (U, (r, th, ph)), Chart (U, (x, y, z))]
      >>> M.atlas()
      [Chart (R^3, (x, y, z)), Chart (U, (r, th, ph)),
       Chart (V, (r, th, ph1)), Chart (V, (r, th, ph2)),
       Chart (U, (x, y, z))]
      >>> c_cartU.valid_coordinates(-Integer(1),Integer(0),Integer(2))
      True
      >>> c_cartU.valid_coordinates(Integer(1),Integer(0),Integer(2))
      False
      >>> c_cart.valid_coordinates(Integer(1),Integer(0),Integer(2))
      True

  A vector frame is naturally associated to each chart:

  Sage

      sage: c_cart.frame()
      Coordinate frame (R^3, (∂/∂x,∂/∂y,∂/∂z))
      sage: c_spher.frame()
      Coordinate frame (U, (∂/∂r,∂/∂th,∂/∂ph))

  [Python]

      >>> from sage.all import *
      >>> c_cart.frame()
      Coordinate frame (R^3, (∂/∂x,∂/∂y,∂/∂z))
      >>> c_spher.frame()
      Coordinate frame (U, (∂/∂r,∂/∂th,∂/∂ph))

  as well as a dual frame (basis of 1-forms):

  Sage

      sage: c_cart.coframe()
      Coordinate coframe (R^3, (dx,dy,dz))
      sage: c_spher.coframe()
      Coordinate coframe (U, (dr,dth,dph))

  Python

      >>> from sage.all import *
      >>> c_cart.coframe()
      Coordinate coframe (R^3, (dx,dy,dz))
      >>> c_spher.coframe()
      Coordinate coframe (U, (dr,dth,dph))

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

  restrict(subset, restrictions=None)

    Return the restriction of the chart to some subset.

    If the current chart is \((U, \varphi)\), a restriction (or subchart) is a chart \((V, \psi)\) such that \(V \subset U\) and \(\psi = \varphi |_V\).

    If such subchart has not been defined yet, it is constructed here.

    The coordinates of the subchart bare the same names as the coordinates of the original chart.

    INPUT:

    - `subset` – open subset \(V\) of the chart domain \(U\)

    - `restrictions` – (default: `None`) list of coordinate restrictions defining the subset \(V\)

    A restriction can be any symbolic equality or inequality involving the coordinates, such as `x > y` or `x^2 + y^2 != 0`. The items of the list `restrictions` are combined with the `and` operator; if some restrictions are to be combined with the `or` operator instead, they have to be passed as a tuple in some single item of the list `restrictions`. For example:

        restrictions = [x > y, (x != 0, y != 0), z^2 < x]

    means `(x > y) and ((x != 0) or (y != 0)) and (z^2 < x)`. If the list `restrictions` contains only one item, this item can be passed as such, i.e. writing `x > y` instead of the single element list `[x > y]`.

    OUTPUT:

    - a `RealDiffChart` \((V, \psi)\)

    EXAMPLES:

    Cartesian coordinates on the unit open disc in \(\RR^2\) as a subchart of the global Cartesian coordinates:

    Sage

        sage: M = Manifold(2, 'R^2')
        sage: c_cart.<x,y> = M.chart() # Cartesian coordinates on R^2
        sage: D = M.open_subset('D') # the unit open disc
        sage: c_cart_D = c_cart.restrict(D, x^2+y^2<1)
        sage: p = M.point((1/2, 0))
        sage: p in D
        True
        sage: q = M.point((1, 2))
        sage: q in D
        False

    Python

        >>> from sage.all import *
        >>> M = Manifold(Integer(2), 'R^2')
        >>> c_cart = M.chart(names=('x', 'y',)); (x, y,) = c_cart._first_ngens(2)# Cartesian coordinates on R^2
        >>> D = M.open_subset('D') # the unit open disc
        >>> c_cart_D = c_cart.restrict(D, x**Integer(2)+y**Integer(2)<Integer(1))
        >>> p = M.point((Integer(1)/Integer(2), Integer(0)))
        >>> p in D
        True
        >>> q = M.point((Integer(1), Integer(2)))
        >>> q in D
        False

    Cartesian coordinates on the annulus \(1 < \sqrt{x^2+y^2} < 2\):

    Sage

        sage: A = M.open_subset('A')
        sage: c_cart_A = c_cart.restrict(A, [x^2+y^2>1, x^2+y^2<4])
        sage: p in A, q in A
        (False, False)
        sage: a = M.point((3/2,0))
        sage: a in A
        True

    [Python]

        >>> from sage.all import *
        >>> A = M.open_subset('A')
        >>> c_cart_A = c_cart.restrict(A, [x**Integer(2)+y**Integer(2)>Integer(1), x**Integer(2)+y**Integer(2)<Integer(4)])
        >>> p in A, q in A
        (False, False)
        >>> a = M.point((Integer(3)/Integer(2),Integer(0)))
        >>> a in A
        True