Sketch change metric. (#423)

* Adds a change_metric and a change_representer
* Apply suggestions from code review
* bump version.

Co-authored-by: Mateusz Baran <[email protected]>

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.6.7"
+version = "0.6.8"
 
 [deps]
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"

src/Manifolds.jl

@@ -108,7 +108,6 @@ using ManifoldsBase:
     AbstractLinearVectorTransportMethod,
     ApproximateInverseRetraction,
     ApproximateRetraction,
-    DifferentiatedRetractionVectorTransport,
     ComponentManifoldError,
     CompositeManifoldError,
     CotangentSpaceType,
@@ -460,6 +459,10 @@ export ×,
     allocate_result,
     base_manifold,
     bundle_projection,
+    change_metric,
+    change_metric!,
+    change_representer,
+    change_representer!,
     check_point,
     check_vector,
     christoffel_symbols_first,
@@ -648,7 +651,10 @@ export get_basis,
     get_coordinates, get_coordinates!, get_vector, get_vector!, get_vectors, number_system
 # differentiation
 export AbstractDiffBackend,
-    AbstractRiemannianDiffBackend, FiniteDifferencesBackend, RiemannianONBDiffBackend
+    AbstractRiemannianDiffBackend,
+    FiniteDifferencesBackend,
+    RiemannianONBDiffBackend,
+    RiemannianProjectionGradientBackend
 export diff_backend, diff_backend!, diff_backends
 # atlases and charts
 export get_point, get_point!, get_parameters, get_parameters!

src/groups/group.jl

@@ -404,7 +404,7 @@ end
 
 Compose elements ``p,q ∈ \mathcal{G}`` using the group operation ``p \circ q``.
 
-For implementing composition on a new group manifold, please overload [`_compose`](@ref)
+For implementing composition on a new group manifold, please overload `_compose`
 instead so that methods with [`Identity`](@ref) arguments are not ambiguous.
 """
 compose(::AbstractGroupManifold, ::Any...)

src/manifolds/CenteredMatrices.jl

@@ -101,7 +101,7 @@ where $c_i = \frac{1}{m}\sum_{j=1}^m p_{j,i}$ for $i = 1, \dots, n$.
 """
 project(::CenteredMatrices, ::Any)
 
-project!(M::CenteredMatrices, q, p) = copyto!(q, p .- mean(p, dims=1))
+project!(::CenteredMatrices, q, p) = copyto!(q, p .- mean(p, dims=1))
 
 @doc raw"""
     project(M::CenteredMatrices, p, X)
@@ -119,7 +119,7 @@ where $c_i = \frac{1}{m}\sum_{j=1}^m x_{j,i}$  for $i = 1, \dots, n$.
 """
 project(::CenteredMatrices, ::Any, ::Any)
 
-project!(M::CenteredMatrices, Y, p, X) = (Y .= X .- mean(X, dims=1))
+project!(::CenteredMatrices, Y, p, X) = (Y .= X .- mean(X, dims=1))
 
 @generated representation_size(::CenteredMatrices{m,n,𝔽}) where {m,n,𝔽} = (m, n)
 

src/manifolds/GeneralizedGrassmann.jl

@@ -57,6 +57,39 @@ function GeneralizedGrassmann(
     return GeneralizedGrassmann{n,k,field,typeof(B)}(B)
 end
 
+@doc raw"""
+    change_representer(M::GeneralizedGrassmann, ::EuclideanMetric, p, X)
+
+Change `X` to the corresponding representer of a cotangent vector at `p` with respect to the scaled metric
+of the [`GeneralizedGrassmann`](@ref) `M`, i.e, since
+
+```math
+g_p(X,Y) = \operatorname{tr}(Y^{\mathrm{H}}BZ) = \operatorname{tr}(X^{\mathrm{H}}Z) = ⟨X,Z⟩
+```
+
+has to hold for all ``Z``, where the repreenter `X` is given, the resulting representer with
+respect to the metric on the [`GeneralizedGrassmann`](@ref) is given by ``Y = B^{-1}X``.
+"""
+change_representer(::GeneralizedGrassmann, ::EuclideanMetric, ::Any, ::Any)
+
+function change_representer!(M::GeneralizedGrassmann, Y, ::EuclideanMetric, p, X)
+    return copyto!(M, Y, p, M.B \ X)
+end
+
+@doc raw"""
+    change_metric(M::GeneralizedGrassmann, ::EuclideanMetric, p X)
+
+Change `X` to the corresponding vector with respect to the metric of the [`GeneralizedGrassmann`](@ref) `M`,
+i.e. let ``B=LL'`` be the Cholesky decomposition of the matrix `M.B`, then the corresponding vector is ``L\X``.
+"""
+change_metric(M::GeneralizedGrassmann, ::EuclideanMetric, ::Any, ::Any)
+
+function change_metric!(M::GeneralizedGrassmann, Y, ::EuclideanMetric, p, X)
+    C2 = cholesky(M.B).L
+    Y .= C2 \ X
+    return Y
+end
+
 @doc raw"""
     check_point(M::GeneralizedGrassmann{n,k,𝔽}, p)
 

src/manifolds/Hyperbolic.jl

@@ -133,7 +133,10 @@ for T in _HyperbolicTypes
         allocate(p::$T, ::Type{P}, dims::Tuple) where {P} = $T(allocate(p.value, P, dims))
 
         @inline Base.copy(p::$T) = $T(copy(p.value))
-        Base.copyto!(q::$T, p::$T) = copyto!(q.value, p.value)
+        function Base.copyto!(q::$T, p::$T)
+            copyto!(q.value, p.value)
+            return q
+        end
 
         Base.similar(p::$T) = $T(similar(p.value))
 

src/manifolds/HyperbolicHyperboloid.jl

@@ -1,3 +1,29 @@
+@doc raw"""
+    change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p, X)
+
+Change the Eucliden representer `X` of a cotangent vector at point `p`.
+We only have to correct for the metric, which means that the sign of the last entry changes, since
+for the result ``Y``  we are looking for a tangent vector such that
+
+```math
+    g_p(Y,Z) = -y_{n+1}z_{n+1} + \sum_{i=1}^n y_iz_i = \sum_{i=1}^{n+1} z_ix_i
+```
+
+holds, which directly yields ``y_i=x_i`` for ``i=1,\ldots,n`` and ``y_{n+1}=-x_{n+1}``.
+"""
+change_representer(::Hyperbolic, ::EuclideanMetric, ::Any, ::Any)
+
+function change_representer!(M::Hyperbolic, Y, ::EuclideanMetric, p, X)
+    copyto!(M, Y, p, X)
+    Y[end] *= -1
+    return Y
+end
+
+function change_metric!(::Hyperbolic, ::Any, ::EuclideanMetric, ::Any, ::Any)
+    return error(
+        "Changing metric from Euclidean to Hyperbolic is not possible (see Sylvester's law of inertia).",
+    )
+end
 
 function check_point(M::Hyperbolic, p; kwargs...)
     mpv = invoke(check_point, Tuple{supertype(typeof(M)),typeof(p)}, M, p; kwargs...)
@@ -325,7 +351,7 @@ component such that for the
 resulting `p` we have that its [`minkowski_metric`](@ref) is $⟨p,X⟩_{\mathrm{M}} = 0$,
 i.e. $X_{n+1} = \frac{⟨\tilde p, Y⟩}{p_{n+1}}$, where $\tilde p = (p_1,\ldots,p_n)$.
 """
-_hyperbolize(M::Hyperbolic, p, Y) = vcat(Y, dot(p[1:(end - 1)], Y) / p[end])
+_hyperbolize(::Hyperbolic, p, Y) = vcat(Y, dot(p[1:(end - 1)], Y) / p[end])
 
 @doc raw"""
     inner(M::Hyperbolic{n}, p, X, Y)

src/manifolds/HyperbolicPoincareBall.jl

@@ -1,3 +1,48 @@
+@doc raw"""
+    change_representer(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)
+
+Since in the metric we have the term `` α = \frac{2}{1-\sum_{i=1}^n p_i^2}`` per element,
+the correction for the gradient reads `` Y = \frac{1}{α^2}X``.
+"""
+change_representer(
+    ::Hyperbolic,
+    ::EuclideanMetric,
+    ::PoincareBallPoint,
+    ::PoincareBallTVector,
+)
+
+function change_representer!(
+    ::Hyperbolic,
+    Y::PoincareBallTVector,
+    ::EuclideanMetric,
+    p::PoincareBallPoint,
+    X::PoincareBallTVector,
+)
+    α = 2 / (1 - norm(p.value)^2)
+    Y.value .= X.value ./ α^2
+    return Y
+end
+
+@doc raw"""
+    change_metric(M::Hyperbolic{n}, ::EuclideanMetric, p::PoincareBallPoint, X::PoincareBallTVector)
+
+Since in the metric we always have the term `` α = \frac{2}{1-\sum_{i=1}^n p_i^2}`` per element,
+the correction for the metric reads ``Z = \frac{1}{α}X``.
+"""
+change_metric(::Hyperbolic, ::EuclideanMetric, ::PoincareBallPoint, ::PoincareBallTVector)
+
+function change_metric!(
+    ::Hyperbolic,
+    Y::PoincareBallTVector,
+    ::EuclideanMetric,
+    p::PoincareBallPoint,
+    X::PoincareBallTVector,
+)
+    α = 2 / (1 - norm(p.value)^2)
+    Y.value .= X.value ./ α
+    return Y
+end
+
 function check_point(M::Hyperbolic{N}, p::PoincareBallPoint; kwargs...) where {N}
     mpv = check_point(Euclidean(N), p.value; kwargs...)
     mpv === nothing || return mpv