convert with optional manifold (#155)

* convert with optional manifold

* Docs

* more docs

Project.toml

@@ -1,7 +1,7 @@
 name = "ManifoldsBase"
 uuid = "3362f125-f0bb-47a3-aa74-596ffd7ef2fb"
 authors = ["Seth Axen <[email protected]>", "Mateusz Baran <[email protected]>", "Ronny Bergmann <[email protected]>", "Antoine Levitt <[email protected]>"]
-version = "0.14.4"
+version = "0.14.5"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

docs/src/example.md

@@ -192,9 +192,14 @@ function exp!(M::ScaledSphere{N}, q, p, X, t::Number) where {N}
     end
     return q
 end
+function exp!(M::ScaledSphere{N}, q, p, X) where {N}
+    exp!(M, q, p, X, 1)
+end
 nothing #hide
 ```
 
+Two variants are implemented above: one with the scaling argument `t` and one without. It isn't always necessary to implement both but doing so reduces the chance of ambiguity errors.
+
 A first easy check can be done taking `p` from above and any vector `X` of length `1.5π` from its tangent space.
 The resulting point is opposite of `p`, i.e. `-p` and it is of course a valid point on `S`.
 

docs/src/types.md

@@ -20,6 +20,8 @@ Usually one can just use any type. When a manifold has multiple representations,
 AbstractManifoldPoint
 ```
 
+Converting points between different representations can be performed using the `convert` function with either two or three arguments (`convert(T, M, p)` or `convert(T, p)`). For some manifolds providing `M` may be necessary. The first variant falls back to the second variant.
+
 ## Tangent and Cotangent spaces
 
 ```@autodocs
@@ -30,6 +32,8 @@ Order = [:type, :function]
 
 This interface also covers a large variety how to [model bases in tangent spaces](@ref bases).
 
+Converting tangent vectors between different representations can be performed using the `convert` function with either three or four arguments (`convert(T, M, p, X)` or `convert(T, p, X)`). For some manifolds providing `M` may be necessary. The first variant falls back to the second variant.
+
 ## Macros for automatic forwards for simple points/tangent vectors
 
 When distinguishing different representations of points or tangent vectors on one manifold,

src/ManifoldsBase.jl

@@ -262,6 +262,19 @@ function check_size(M::AbstractManifold, p, X)
     end
 end
 
+"""
+    convert(T::Type, M::AbstractManifold, p)
+
+Convert point `p` from manifold `M` to type `T`.
+"""
+convert(T::Type, ::AbstractManifold, p) = convert(T, p)
+"""
+    convert(T::Type, M::AbstractManifold, p, X)
+
+Convert vector `X` tangent at point `p` from manifold `M` to type `T`.
+"""
+convert(T::Type, ::AbstractManifold, p, X) = convert(T, p, X)
+
 @doc raw"""
     copy(M::AbstractManifold, p)
 

test/default_manifold.jl

@@ -43,6 +43,7 @@ struct DefaultTVector{T} <: TVector
     value::T
 end
 DefaultTVector(v::T) where {T} = DefaultTVector{T}(v)
+convert(::Type{DefaultTVector{T}}, ::DefaultPoint, v::T) where {T} = DefaultTVector(v)
 Base.size(X::DefaultTVector) = size(X.value)
 Base.eltype(X::DefaultTVector) = eltype(X.value)
 function Base.fill!(X::DefaultTVector, x)
@@ -809,6 +810,10 @@ Base.size(x::MatrixVectorTransport) = (size(x.m, 2),)
         @test parallel_transport_to!(M, Y, p, X, q) == X
         @test parallel_transport_direction!(M, Y, p, X, X) == X
         @test parallel_transport_along!(M, Y, p, X, []) == X
+
+        # convert with manifold
+        @test convert(typeof(p), M, p.value) == p
+        @test convert(typeof(X), M, p, X.value) == X
     end
 
     @testset "DefaultManifold and ONB" begin