Introduce the Weingarten map. (#163)

* Introduce the Weingarten map.
* Get `News.md` back up to date.

---------

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

NEWS.md

@@ -5,7 +5,73 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.14.0]
+## [0.14.10] 17/08/2023
+
+### Added
+
+- introduce the `Weingarten` map and its in place variant `Weingarten!`.
+
+## [0.14.9] 03/08/2023
+
+### Added
+
+- Introduce an interface that allows the static size of a manifold to be a field as well.
+
+## [0.14.8] 07/07/2023
+
+### Changed
+
+- Improve `show` for cached bases and make it more robust
+
+## [0.14.7] 07/07/2023
+
+### Changed
+
+- the tutorial is now written in Quarto.
+
+## [0.14.6] 10/06/2023
+
+### Added
+
+- export the inplace random function `rand!`
+
+## [0.14.5] 03/05/2023
+
+### Added
+
+- Allow to specify an `AbstractManifold` when converting points or tangent vector types.
+
+## [0.14.4] 10/04/2023
+
+### Changed
+
+- Fix `copy` to work properly when copying `Number`s
+
+## [0.14.3] 16/03/2023
+
+### Changed
+
+- Fix an allocation bug in nested power manifolds
+
+## [0.14.2] 16/03/2023
+
+### Added
+
+- adds a DependaBot workflow.
+
+### Changed
+
+- Fix an allocation issue with `exp(M, p, X, t)` that did not respect the type of `t`.
+
+## [0.14.1] 18/02/2023
+
+Note that this release did not trigger a TagBot, so it appears within 0.14.2 in the tagged/created releases
+
+### Added
+
+- Introduce `change_representer` already in `ManifoldsBase`.
+
+## [0.14.0] – 15/02/2023
 
 ### Added
 

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.9"
+version = "0.14.10"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

src/DefaultManifold.jl

@@ -171,6 +171,8 @@ function riemann_tensor!(::DefaultManifold, Xresult, p, X, Y, Z)
     return fill!(Xresult, 0)
 end
 
+Weingarten!(::DefaultManifold, Y, p, X, V) = fill!(Y, 0)
+
 zero_vector(::DefaultManifold, p) = zero(p)
 
 zero_vector!(::DefaultManifold, Y, p) = fill!(Y, 0)

src/ManifoldsBase.jl

@@ -907,6 +907,39 @@ Converts a size given by `Tuple{N, M, ...}` into a tuple `(N, M, ...)`.
 """
 Base.@pure size_to_tuple(::Type{S}) where {S<:Tuple} = tuple(S.parameters...)
 
+@doc raw"""
+    Weingarten!(M, Y, p, X, V)
+
+Compute the Weingarten map ``\mathcal W_p\colon T_p\mathcal M × N_p\mathcal M \to T_p\mathcal M``
+in place of `Y`, see [`Weingarten`](@ref).
+"""
+Weingarten!(M::AbstractManifold, Y, p, X, V)
+
+@doc raw"""
+    Weingarten(M, p, X, V)
+
+Compute the Weingarten map ``\mathcal W_p\colon T_p\mathcal M × N_p\mathcal M \to T_p\mathcal M``,
+where ``N_p\mathcal M`` is the orthogonal complement of the tangent space ``T_p\mathcal M``
+of the embedded submanifold ``\mathcal M``, where we denote the embedding by ``\mathcal E``.
+
+The Weingarten map can be defined by restricting the differential of the orthogonal [`project`](@ref)ion
+``\operatorname{proj}_{T_p\mathcal M}\colon T_p \mathcal E \to T_p\mathcal M`` with respect to the base point ``p``,
+i.e. defining
+```math
+\mathcal P_X \coloneqq D_p\operatorname{proj}_{T_p\mathcal M}(Y)[X],
+\qquad Y \in T_p \mathcal E, X \in T_p\mathcal M,
+```
+the Weingarten map can be written as ``\mathcal W_p(X,V) = \mathcal P_X(V)``.
+
+The Weingarten map is named after [Julius Weingarten](https://en.wikipedia.org/wiki/Julius_Weingarten) (1836–1910).
+"""
+function Weingarten(M::AbstractManifold, p, X, V)
+    Y = copy(M, p, X)
+    Weingarten!(M, Y, p, X, V)
+    return Y
+end
+
+
 @doc raw"""
     zero_vector!(M::AbstractManifold, X, p)
 
@@ -1086,6 +1119,8 @@ export allocate,
     vector_transport_to!,
     vee,
     vee!,
+    Weingarten,
+    Weingarten!,
     zero_vector,
     zero_vector!
 

test/default_manifold.jl

@@ -482,6 +482,7 @@ Base.size(x::MatrixVectorTransport) = (size(x.m, 2),)
                 tv = similar(tv1)
                 embed!(M, tv, pts[1], tv1)
                 @test isapprox(M, pts[1], tv, tv1)
+                @test Weingarten(M, pts[1], tv, tv) == zero_vector(M, pts[1])
             end
 
             @testset "randon tests" begin

test/test_sphere.jl

@@ -51,6 +51,11 @@ function ManifoldsBase.project!(::TestSphere, Y, p, X)
     return Y
 end
 
+# from Absil, Mahony, Trumpf, 2013 https://sites.uclouvain.be/absil/2013-01/Weingarten_07PA_techrep.pdf
+function ManifoldsBase.Weingarten!(::TestSphere, Y, p, X, V)
+    return Y .= -X * p' * V
+end
+
 @testset "TestSphere" begin
     @testset "ShootingInverseRetraction" begin
         vector_transports =
@@ -84,4 +89,11 @@ end
             end
         end
     end
+    @testset "Weingarten" begin
+        M = TestSphere(2)
+        p = [1.0, 0.0, 0.0]
+        X = [0.0, 0.2, 0.0]
+        V = [0.1, 0.0, 0.0] #orthogonal to TpM -> parallel to p
+        @test isapprox(M, p, Weingarten(M, p, X, V), -0.1 * X)
+    end
 end