Implement translate_diff and inv_diff for all groups (#679)

NEWS.md

@@ -5,6 +5,17 @@ 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.9.21] – unreleased
+
+### Changed
+
+* `translate_diff`, `inv_diff` and thus `apply_diff_group`, are available for all the groups
+* `adjoint_action` takes a direction argument
+* `adjoint_action!` is the necessary method to implement in any given group for the above to work properly
+* On groups, `exp` and `log` are based on `exp_lie` and `log_lie` and thus group invariant
+* fixed a few typos in the doc string of the SPD fixed determinant description.
+
 ## [0.9.20] – 2024-06-17
 
 ### Added

docs/src/manifolds/group.md

@@ -43,6 +43,56 @@ Pages = ["groups/GroupManifold.jl"]
 Order = [:constant, :type, :function]
 ```
 
+### Default Storage of Tangent Vectors
+
+In most groups, the storage of a tangent vector
+ ``X`` at the point ``p ∈ \mathcal{G}`` is stored
+ as a vector ``Y ∈ \mathfrak{g}``.
+This helps to compute the derivatives of the composition and inverse.
+
+To explain this, let us assume that *the group consists of matrices* (this is always possible).
+The storage of a tangent vector
+ ``X`` at the point ``p ∈ \mathcal{G}`` is stored
+ as the vector ``Y ∈ \mathfrak{g}`` given by
+```math
+X = pY
+```
+
+#### Derivative of the Group Composition on the Left
+
+The derivative of the composition ``pq`` with respect to ``p`` in
+the direction ``X``, tangent at ``p`` is given by
+```math
+Xq = pYq = pq(q^{-1}Yq)
+```
+We see that with this storage convention, this derivative is just the
+adjoint action of ``q^{-1}`` on the vector ``Y``.
+
+#### Derivative of the Group Composition on the Right
+
+For the derivative with respect to ``q`` of the composition ``pq`` at a tangent vector ``X`` at ``q``
+stored as ``Y`` with ``X = qY``, we have similarly
+```math
+pX = pqY
+```
+With the storage convention above, this derivative is just the identity.
+
+#### Derivative of the Group Inverse
+
+Finally, we look at the derivative of the inverse ``p^{-1}`` at a point ``p`` in a tangent direction ``X``
+at ``p`` with ``X = pY``.
+The result is a tangent vector at ``p^{-1}`` given by
+```math
+-p^{-1}Xp^{-1} = - Yp^{-1} = -p^{-1}(p Y p^{-1})
+```
+With the storage convention above, this derivative is thus ``-pYp^{-1}``, that is, the opposite of the adjoint action of ``p`` on the vector ``Y``.
+
+#### Implication for Creating New Groups
+
+When you create a new group,
+defining the adjoint action alone ([`adjoint_action`](@ref))
+automatically defines all the relevant derivatives above.
+
 ### Generic Operations
 
 For groups based on an addition operation or a group operation, several default implementations are provided.

ext/ManifoldsTestExt/tests_group.jl

@@ -114,7 +114,13 @@
     test_adjoint_action::Bool=false,
     test_inv_diff::Bool=false,
     test_adjoint_inv_diff::Bool=false,
-    diff_convs=[(), (LeftForwardAction(),), (RightBackwardAction(),)],
+    diff_convs=[
+        (),
+        (LeftForwardAction(),),
+        (RightBackwardAction(),),
+        (LeftBackwardAction(),),
+        (RightForwardAction(),),
+    ],
     test_log_from_identity::Bool=false,
     test_exp_from_identity::Bool=false,
     test_vee_hat_from_identity::Bool=false,
@@ -379,6 +385,12 @@
         Test.@testset "test_inv_diff" for side in [LeftSide(), RightSide()]
             test_inv_diff_fn(G, g_pts[1], X_pts[1], side)
         end # COV_EXCL_LINE
+        if test_mutating
+            Y = inv_diff(G, e, Xe_pts[1])
+            Z = allocate(Y)
+            inv_diff!(G, Z, e, Xe_pts[1])
+            Test.@test isapprox(TangentSpace(G, e), Y, Z)
+        end
     end
     test_adjoint_inv_diff && Test.@testset "Differential of inverse" begin # COV_EXCL_LINE
         Test.@test isapprox(adjoint_inv_diff(G, e, Xe_pts[1]), -Xe_pts[1]; atol=atol)
@@ -534,10 +546,27 @@
             adjoint_action(G, g_pts[2], adjoint_action(G, inv(G, g_pts[2]), X)),
             X,
         )
+        # right adjoint action
+        Test.@test isapprox(
+            G,
+            e,
+            adjoint_action(G, g_pts[2], adjoint_action(G, g_pts[2], X, RightAction())),
+            X,
+        )
+        # adjoint action at identity
+        for conv in [LeftAction(), RightAction()]
+            isapprox(
+                TangentSpace(G, identity_element(G)),
+                adjoint_action(G, e, Xe_pts[1], conv),
+                Xe_pts[1],
+            )
+        end
         if test_mutating
             Z = allocate(X)
             adjoint_action!(G, Z, g_pts[2], X)
             Test.@test isapprox(G, e, Z, adjoint_action(G, g_pts[2], X))
+            adjoint_action!(G, Z, g_pts[2], X, RightAction())
+            Test.@test isapprox(G, e, Z, adjoint_action(G, g_pts[2], X, RightAction()))
         end
 
         # interaction with Lie bracket

src/groups/addition_operation.jl

@@ -22,9 +22,16 @@
 
 const AdditionGroupTrait = TraitList{<:IsGroupManifold{AdditionOperation}}
 
-adjoint_action(::AdditionGroupTrait, G::AbstractDecoratorManifold, p, X) = X
+adjoint_action(::AdditionGroupTrait, G::AbstractDecoratorManifold, p, X, ::LeftAction) = X
 
-function adjoint_action!(::AdditionGroupTrait, G::AbstractDecoratorManifold, Y, p, X)
+function adjoint_action!(
+    ::AdditionGroupTrait,
+    G::AbstractDecoratorManifold,
+    Y,
+    p,
+    X,
+    ::LeftAction,
+)
     return copyto!(G, Y, p, X)
 end
 
@@ -74,14 +81,7 @@
 
 Compute the value of differential of additive matrix inversion ``p ↦ -p`` at ``X``, i.e. ``-X``.
 """
-function inv_diff(::AdditionGroupTrait, G::AbstractDecoratorManifold, p, X)
-    return -X
-end
-function inv_diff!(::AdditionGroupTrait, G::AbstractDecoratorManifold, Y, p, X)
-    Y .= X
-    Y .*= -1
-    return Y
-end
+inv_diff(::AdditionGroupTrait, G::AbstractDecoratorManifold, p, X)
 
 function is_identity(
     ::AdditionGroupTrait,
@@ -165,26 +165,3 @@
 lie_bracket(::AdditionGroupTrait, G::AbstractDecoratorManifold, X, Y) = zero(X)
 
 lie_bracket!(::AdditionGroupTrait, G::AbstractDecoratorManifold, Z, X, Y) = fill!(Z, 0)
-
-function translate_diff(
-    ::AdditionGroupTrait,
-    G::AbstractDecoratorManifold,
-    p,
-    q,
-    X,
-    ::ActionDirectionAndSide,
-)
-    return X
-end
-
-function translate_diff!(
-    ::AdditionGroupTrait,
-    G::AbstractDecoratorManifold,
-    Y,
-    p,
-    q,
-    X,
-    ::ActionDirectionAndSide,
-)
-    return copyto!(G, Y, p, X)
-end

src/groups/circle_group.jl

@@ -24,9 +24,13 @@
 
 Base.show(io::IO, ::CircleGroup) = print(io, "CircleGroup()")
 
-adjoint_action(::CircleGroup, p, X) = X
+adjoint_action(::CircleGroup, p, X, ::LeftAction) = X
+adjoint_action(::CircleGroup, ::Identity, X, ::LeftAction) = X
+adjoint_action(::CircleGroup, p, X, ::RightAction) = X
+adjoint_action(::CircleGroup, ::Identity, X, ::RightAction) = X
 
-adjoint_action!(::CircleGroup, Y, p, X) = copyto!(Y, X)
+adjoint_action!(::CircleGroup, Y, p, X, ::LeftAction) = copyto!(Y, X)
+adjoint_action!(::CircleGroup, Y, p, X, ::RightAction) = copyto!(Y, X)
 
 function compose(
     ::MultiplicationGroupTrait,
@@ -77,21 +81,37 @@
 
 lie_bracket!(::CircleGroup, Z, X, Y) = fill!(Z, 0)
 
-function translate_diff(::GT, p, q, X, ::ActionDirectionAndSide) where {GT<:CircleGroup}
-    return map(*, p, X)
-end
-function translate_diff(
-    ::CircleGroup,
-    ::Identity{MultiplicationOperation},
-    q,
-    X,
-    ::ActionDirectionAndSide,
-)
-    return X
+translate_diff(::CircleGroup, p, q, X) = map(*, p, X)
+translate_diff(::CircleGroup, p::Identity{MultiplicationOperation}, q, X) = X
+for AD in [LeftForwardAction, RightForwardAction, LeftBackwardAction, RightBackwardAction]
+    @eval begin
+        function translate_diff(G::CircleGroup, p, q, X, ::$AD)
+            return translate_diff(G, p, q, X)
+        end
+        function translate_diff(
+            ::CircleGroup,
+            ::Identity{MultiplicationOperation},
+            q,
+            X,
+            ::$AD,
+        )
+            return X
+        end
+    end
 end
 
-function translate_diff!(G::CircleGroup, Y, p, q, X, conv::ActionDirectionAndSide)
-    return copyto!(Y, translate_diff(G, p, q, X, conv))
+_common_translate_diff!(G, Y, p, q, X, conv) = copyto!(Y, translate_diff(G, p, q, X, conv))
+function translate_diff!(G::CircleGroup, Y, p, q, X, conv::LeftForwardAction)
+    return _common_translate_diff!(G, Y, p, q, X, conv)
+end
+function translate_diff!(G::CircleGroup, Y, p, q, X, conv::RightForwardAction)
+    return _common_translate_diff!(G, Y, p, q, X, conv)
+end
+function translate_diff!(G::CircleGroup, Y, p, q, X, conv::LeftBackwardAction)
+    return _common_translate_diff!(G, Y, p, q, X, conv)
+end
+function translate_diff!(G::CircleGroup, Y, p, q, X, conv::RightBackwardAction)
+    return _common_translate_diff!(G, Y, p, q, X, conv)
 end
 
 function exp_lie(::CircleGroup, X)
@@ -143,6 +163,17 @@
     end
 end
 
+adjoint_action(::RealCircleGroup, p, X, ::LeftAction) = X
+adjoint_action(::RealCircleGroup, p, X, ::RightAction) = X
+adjoint_action(::RealCircleGroup, ::Identity, X, ::LeftAction) = X
+adjoint_action(::RealCircleGroup, ::Identity, X, ::RightAction) = X
+
+for AD in [LeftAction, RightAction]
+    @eval begin
+        adjoint_action!(::RealCircleGroup, Y, p, X, ::$AD) = copyto!(Y, X)
+    end
+end
+
 Base.show(io::IO, ::RealCircleGroup) = print(io, "RealCircleGroup()")
 
 is_default_metric(::RealCircleGroup, ::EuclideanMetric) = true
@@ -198,3 +229,21 @@
 end
 
 exp_lie!(::RealCircleGroup, q, X) = (q .= sym_rem(X))
+
+translate_diff(::RealCircleGroup, p, q, X) = X
+for AD in [LeftForwardAction, RightForwardAction, LeftBackwardAction, RightBackwardAction]
+    @eval begin
+        function translate_diff(::RealCircleGroup, p, q, X, ::$AD)
+            return X
+        end
+        function translate_diff(
+            ::RealCircleGroup,
+            ::Identity{AdditionOperation},
+            q,
+            X,
+            ::$AD,
+        )
+            return X
+        end
+    end
+end

src/groups/general_linear.jl

@@ -275,9 +275,6 @@
     return print(io, "GeneralLinear($n, $(𝔽); parameter=:field)")
 end
 
-translate_diff(::GeneralLinear, p, q, X, ::LeftForwardAction) = X
-translate_diff(::GeneralLinear, p, q, X, ::RightBackwardAction) = p \ X * p
-
-function translate_diff!(G::GeneralLinear, Y, p, q, X, conv::ActionDirectionAndSide)
-    return copyto!(Y, translate_diff(G, p, q, X, conv))
-end
+# note: this implementation is not optimal
+adjoint_action!(::GeneralLinear, Y, p, X, ::LeftAction) = copyto!(Y, p * X * inv(p))
+adjoint_action!(::GeneralLinear, Y, p, X, ::RightAction) = copyto!(Y, p \ X * p)

src/groups/general_unitary_groups.jl

@@ -287,46 +287,20 @@
     return manifold_volume(M.manifold)
 end
 
-function translate_diff!(
-    G::GeneralUnitaryMultiplicationGroup,
-    Y,
-    p,
-    q,
-    X,
-    ::LeftForwardAction,
-)
-    return copyto!(G, Y, X)
+function Random.rand!(G::GeneralUnitaryMultiplicationGroup, pX; kwargs...)
+    rand!(G.manifold, pX; kwargs...)
+    return pX
 end
-function translate_diff!(
-    G::GeneralUnitaryMultiplicationGroup,
-    Y,
-    p,
-    q,
-    X,
-    ::RightForwardAction,
-)
-    copyto!(G, Y, X)
-    return Y
+function Random.rand!(rng::AbstractRNG, G::GeneralUnitaryMultiplicationGroup, pX; kwargs...)
+    rand!(rng, G.manifold, pX; kwargs...)
+    return pX
 end
-function translate_diff!(
-    G::GeneralUnitaryMultiplicationGroup,
-    Y,
-    p,
-    q,
-    X,
-    ::LeftBackwardAction,
-)
+
+function adjoint_action!(G::GeneralUnitaryMultiplicationGroup, Y, p, X, ::LeftAction)
     copyto!(G, Y, p * X * inv(G, p))
     return Y
 end
-function translate_diff!(
-    G::GeneralUnitaryMultiplicationGroup,
-    Y,
-    p,
-    q,
-    X,
-    ::RightBackwardAction,
-)
+function adjoint_action!(G::GeneralUnitaryMultiplicationGroup, Y, p, X, ::RightAction)
     return copyto!(G, Y, inv(G, p) * X * p)
 end