Atlases and charts

CONTRIBUTING.md

@@ -50,7 +50,7 @@ The non-mutating one (e.g. `exp`) always falls back to use the mutating one, so
 suffice to implement the mutating one (e.g. `exp!`).
 
 Note that since the first argument is _always_ the [`Manifold`](https://juliamanifolds.github.io/Manifolds.jl/latest/interface.html#ManifoldsBase.Manifold), the mutated argument is always the second one in the signature.
-In the example we have `exp(M, x, v)` for the exponential map and `exp!(M, y, v, x)` for the mutating one, that stores the result in `y`.
+In the example we have `exp(M, p, X)` for the exponential map and `exp!(M, q, X, p)` for the mutating one, that stores the result in `q`.
 
 On the other hand, the user will most likely look for the documentation of the non-mutating version, so we recommend adding the docstring for the non-mutating one, where all different signatures should be collected in one string when reasonable.
 This can best be achieved by adding a docstring to the method with a general signature with the first argument being your manifold:
@@ -59,7 +59,7 @@ This can best be achieved by adding a docstring to the method with a general sig
 struct MyManifold <: Manifold end
 
 @doc raw"""
-    exp(M::MyManifold, x, v)
+    exp(M::MyManifold, p, X)
 
 Describe the function.
 """

Project.toml

@@ -1,7 +1,7 @@
 name = "Manifolds"
 uuid = "1cead3c2-87b3-11e9-0ccd-23c62b72b94e"
 authors = ["Seth Axen <[email protected]>", "Mateusz Baran <[email protected]>", "Ronny Bergmann <[email protected]>", "Antoine Levitt <[email protected]>"]
-version = "0.4.17"
+version = "0.5.0"
 
 [deps]
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"

docs/make.jl

@@ -69,6 +69,7 @@ makedocs(
             ],
         ],
         "Features on Manifolds" => [
+            "Atlases and charts" => "features/atlases.md",
             "Differentiation" => "features/differentiation.md",
             "Distributions" => "features/distributions.md",
             "Statistics" => "features/statistics.md",

docs/src/features/atlases.md

@@ -0,0 +1,44 @@
+# [Atlases and charts](@id atlases_and_charts)
+
+Atlases on an $n$-dimensional manifold $\mathcal M$ are collections of charts $\{(U_i, \varphi_i) \colon i \in I\}$ such that $U_i \subseteq \mathcal M$ and each chart $\varphi_i$ is a function from $U_i$ to $\mathbb{R}^n$.
+They provide a basic connection between manifolds and Euclidean spaces.
+
+Most operations on manifolds in `Manifolds.jl` avoid operating in a chart through appropriate embeddings and formulas derived for particular manifolds, though atlases provide the most general way of working with manifolds.
+They are extensively used in metric-related functions on [`MetricManifold`](@ref Main.Manifolds.MetricManifold)s.
+
+Atlases are represented by objects of subtypes of [`AbstractAtlas`](@ref Main.Manifolds.AbstractAtlas).
+There are no type restrictions for indices of charts in atlases.
+
+Operations using atlases and charts are available through the following functions:
+
+* [`get_chart_index`](@ref Main.Manifolds.get_chart_index) can be used to select an appropriate chart for the neighborhood of a given point.
+* [`get_point_coordinates`](@ref Main.Manifolds.get_point_coordinates) converts a point to its coordinates in a chart.
+* [`get_point`](@ref Main.Manifolds.get_point) converts coordinates in a chart to the point that corresponds to them.
+* [`induced_basis`](@ref Main.Manifolds.induced_basis) returns a basis of a given vector space at a point induced by a chart.
+* [`transition_map`](@ref Main.Manifolds.transition_map) converts coordinates of a point between two charts.
+
+```@autodocs
+Modules = [Manifolds,ManifoldsBase]
+Pages = ["atlases.jl"]
+Order = [:type, :function]
+```
+
+## Cotangent space
+
+Related to atlases, there is also support for the cotangent space and coefficients of
+cotangent vectors in bases of the cotangent space.
+
+```@autodocs
+Modules = [Manifolds,ManifoldsBase]
+Pages = ["cotangent_space.jl"]
+Order = [:type, :function]
+```
+
+## Musical isomorphisms
+
+Functions [`sharp`](@ref) and [`flat`](@ref) implement musical isomorphisms for arbitrary vector bundles.
+
+```@docs
+sharp
+flat
+```

docs/src/features/differentiation.md

@@ -16,4 +16,4 @@ Order = [:type, :function, :constant]
 Modules = [Manifolds]
 Pages = ["riemannian_diff.jl"]
 Order = [:type, :function, :constant]
-```
+```

docs/src/interface.md

@@ -63,16 +63,20 @@ julia> y[1]
  6.90031725726027e-310
 ```
 
-* [`allocate_result`](@ref) allocates a result of a particular function (for example [`exp`], [`flat`], etc.) on a particular manifold with particular arguments.
+* [`allocate_result`](@ref) allocates a result of a particular function (for example [`exp`](@ref), [`flat`](@ref), etc.) on a particular manifold with particular arguments.
   It takes into account the possibility that different arguments may have different numeric [`number_eltype`](@ref) types thorough the [`ManifoldsBase.allocate_result_type`](@ref) function.
 
 ## Bases
 
-The following functions and types provide support for bases of the tangent space of different manifolds.
+The following functions and types provide support for bases of a the tangent space of different manifolds.
+Moreover, bases of the cotangent space are also supported, though this description focuses on the tangent space.
 An orthonormal basis of the tangent space $T_p \mathcal M$ of (real) dimension $n$ has a real-coefficient basis $e_1, e_2, …, e_n$ if $\mathrm{Re}(g_p(e_i, e_j)) = δ_{ij}$ for each $i,j ∈ \{1, 2, …, n\}$ where $g_p$ is the Riemannian metric at point $p$.
 A vector $X$ from the tangent space $T_p \mathcal M$ can be expressed in Einstein notation as a sum $X = X^i e_i$, where (real) coefficients $X^i$ are calculated as $X^i = \mathrm{Re}(g_p(X, e_i))$.
 
+Bases are closely related to [atlases](@ref atlases_and_charts).
+
 The main types are:
+
 * [`DefaultOrthonormalBasis`](@ref), which is designed to work when no special properties of the tangent space basis are required.
    It is designed to make [`get_coordinates`](@ref) and [`get_vector`](@ref) fast.
 * [`DiagonalizingOrthonormalBasis`](@ref), which diagonalizes the curvature tensor and makes the curvature in the selected direction equal to 0.
@@ -86,12 +90,20 @@ The main functions are:
 * [`get_vector`](@ref) returns a vector for the specified coordinates.
 * [`get_vectors`](@ref) returns a vector of basis vectors. Calling it should be avoided for high-dimensional manifolds.
 
+Coordinates of a vector in a basis can be stored in an [`FVector`](@ref) to explicitly indicate which basis they are expressed in. It is useful to avoid potential ambiguities.
+
 ```@autodocs
 Modules = [ManifoldsBase,Manifolds]
 Pages = ["bases.jl"]
 Order = [:type, :function]
 ```
 
+```@autodocs
+Modules = [ManifoldsBase,Manifolds]
+Pages = ["vector_spaces.jl"]
+Order = [:type, :function]
+```
+
 ## Vector transport
 
 There are three main functions for vector transport:
@@ -143,8 +155,8 @@ Order = [:macro, :type, :function]
 ## Abstract Power Manifold
 
 ```@autodocs
-Modules = [ ManifoldsBase]
-Pages = ["PowerManifold.jl"]
+Modules = [Manifolds, ManifoldsBase]
+Pages = ["src/PowerManifold.jl"]
 Order = [:macro, :type, :function]
 ```
 

docs/src/manifolds/sphere.md

@@ -17,6 +17,12 @@ To create the unit sphere of $3×2$ real-valued matrices, write `ArraySphere(3,2
 ArraySphere
 ```
 
+There is also one atlas available on the sphere.
+
+```@docs
+Manifolds.StereographicAtlas
+```
+
 ## Functions on unit spheres
 ```@autodocs
 Modules = [Manifolds]

docs/src/misc/notation.md

@@ -12,6 +12,7 @@ Within the documented functions, the utf8 symbols are used whenever possible, as
 | ``\tau_p`` | action map by group element ``p`` | ``\mathrm{L}_p``, ``\mathrm{R}_p`` | either left or right |
 | ``\times`` | Cartesian product of two manifolds | | see [`ProductManifold`](@ref) |
 | ``^{\wedge}`` | (n-ary) Cartesian power of a manifold | | see [`PowerManifold`](@ref) |
+| ``a`` | coordinates of a point in a chart | | see [`Manifolds.get_point_coordinates`](@ref) |
 | ``T^*_p \mathcal M`` | the cotangent space at ``p`` | | |
 | ``\xi`` | a cotangent vector from ``T^*_p \mathcal M`` | ``\xi_1, \xi_2,\ldots,\eta,\zeta`` | sometimes written with base point ``\xi_p``. |
 | ``\mathrm{d}\phi_p(q)`` | Differential of a map ``\phi: \mathcal M \to \mathcal N`` with respect to ``p`` at a point ``q``. For functions of multiple variables, for example ``\phi(p, p_1)`` where ``p \in \mathcal M`` and ``p_1 \in \mathcal M_1``, variable ``p`` is explicitly stated to specify with respect to which argument the differential is calculated. | ``\mathrm{d}\phi_q``, ``(\mathrm{d}\phi)_q``, ``(\phi_*)_q``, ``D_p\phi(q)`` | pushes tangent vectors ``X \in T_q \mathcal M`` forward to ``\mathrm{d}\phi_p(q)[X] \in T_{\phi(q)} \mathcal N`` |

src/Manifolds.jl

@@ -17,6 +17,7 @@ import ManifoldsBase:
     decorator_transparent_dispatch,
     default_decorator_dispatch,
     distance,
+    dual_basis,
     embed,
     embed!,
     exp!,
@@ -53,12 +54,15 @@ import ManifoldsBase:
     retract,
     retract!,
     set_component!,
+    vector_space_dimension,
     vector_transport_direction,
     vector_transport_direction!,
     vector_transport_to,
     vector_transport_to!,
-    zero_tangent_vector,
-    zero_tangent_vector!
+    zero_vector,
+    zero_vector!,
+    CotangentSpace,
+    TangentSpace
 import Base: copyto!, convert, in, isapprox, isempty, length, showerror
 
 using Base.Iterators: repeated
@@ -82,17 +86,24 @@ using ManifoldsBase:
     AbstractPowerRepresentation,
     AbstractVectorTransportMethod,
     AbstractLinearVectorTransportMethod,
-    DifferentiatedRetractionVectorTransport,
     ComponentManifoldError,
     CompositeManifoldError,
+    CotangentSpaceType,
+    CoTFVector,
     DefaultManifold,
     DefaultOrDiagonalizingBasis,
     DiagonalizingBasisData,
+    DifferentiatedRetractionVectorTransport,
+    FVector,
     InversePowerRetraction,
     PowerManifold,
     PowerManifoldNested,
     PowerRetraction,
     PowerVectorTransport,
+    TangentSpaceType,
+    TCoTSpaceType,
+    TFVector,
+    VectorSpaceType,
     VeeOrthogonalBasis,
     @decorator_transparent_fallback,
     @decorator_transparent_function,
@@ -119,6 +130,9 @@ using StatsBase
 using StatsBase: AbstractWeights
 
 include("utils.jl")
+
+include("atlases.jl")
+include("cotangent_space.jl")
 include("differentiation.jl")
 include("riemannian_diff.jl")
 
@@ -461,9 +475,7 @@ export ×,
     vee,
     vee!,
     zero_vector,
-    zero_vector!,
-    zero_tangent_vector,
-    zero_tangent_vector!
+    zero_vector!
 # Lie group types & functions
 export AbstractGroupAction,
     AbstractGroupOperation,