initial sketch of group actions

* initial sketch of actions
* Fix news.
* add a reference.
* improve documentation.

---------

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

NEWS.md

@@ -11,21 +11,39 @@ Everything denoted by “formerly” refers to the previous name in [`Manifolds.
 
 ### Added
 
+* `LieAlgebra`
+* `LieGroup` (formerly `GroupManifold`) as well as the concrete groups
+  * `AdditiveGroup` (formerly `TranslationGroup`)
+* `AbstractGroupOperation` as well as its concrete subtypes
+  * `AdditiveGroupOperation`
+* `AbstractGroupActionType` with its 2 specific (new) abstract
+  * `AbstractLeftGroupActionType`
+  * `AbstractRightGroupActionType`
+* For the group operation actions there are now
+  * `LeftGroupOperation` (formerly `LeftForwardAction`)
+  * `RightGroupOperation` (formerly `RightBackwardAction`)
+  * `InverseLeftGroupOperation` (formerly `RightForwardAction`)
+  * `InverseRightGroupOperation` (formerly `LeftBackwardAction`)
+* `LieGroups.AbstractGroupOperation` as well as its concrete subtypes
+  * `AdditiveGroupOperation`
+* `apply`and `apply!`
+* `base_manifold` to access the manifold within a Lie group
 * `compose` and `compose!`
-* `compose_diff_left`, `compose_diff_left!`, `compose_diff_right`, `compose_diff_right!` (formerly `translate_diff` with different sides)
-* `compose_inv_left` and `compose_inv_right` (formerly only the `inverse_translate` but it had modes that also just did compose, the odes here are `LeftForward` and `RightBackward`)
 * `conjugate` and `conjugate!`
+* `diff_apply`, `diff_apply!`, `diff_group_apply`, and `diff_group_apply!` (formerly `apply_diff_[group][!]`)
+* `diff_left_compose`, `diff_left_compose!`, `diff_right_compose`, `diff_right_compose!` (formerly `translate_diff` with different sides)
 * `exp(G::LieGroup, g, X)` and `exp!(G::LieGroup, h, g, X)` (formerly `exp_inv` and `exp_inv!`)
 * `exp(G::LieGroup, ::Identity, X)` and `exp!(G::LieGroup, h, ::Identity, X)` (formerly `exp_lie` and `exp_lie!`)
 * `Identity`
 * `idenity_element` and `identity_element!`
+* `inv` and `inv!` (`inv(::AbstractGroupAction)` was formerly `switch_direction`)
+* `inv_left_compose`, `inv_left_compose!` and `inv_right_compose`, `inv_right_compose!` (these functions correspond to `inverse_translate` with corresponding direction and side)
 * `is_identity`
-* `inv` and `inv!`
 * `Lie_bracket` and `Lie_bracket!` (formerly `lie_bracket`)
 * `log(G::LieGroup, g, h)` and `log!(G::LieGroup, X, g, h)` (formerly `log_inv` and `log_inv!`)
 * `log(G::LieGroup, ::Identity, g)` and `log!(G::LieGroup, X, ::Identity, g)` (formerly `log_lie` and `log_lie!`)
-* `base_manifold` to access the manifold within a Lie group
-* `LieGroup` (formerly `GroupManifold`) as well as the concrete groups
-  * `AdditiveGroup` (formerly `TranslationGroup`)
-* `LieGroups.AbstractGroupOperation` as well as its concrete subtypes
-  * `AdditiveGroupOperation`
+* `switch` (formerly `switch_side`)
+
+Compared to `Manifolds.jl`
+* all `translate` functions are not implemented here, since you can just use `compose`. The differentials are implemented as listed above with respect to both left and right argument of compose
+* all `inverse_apply` functions are not implemented here, since it is recommended to use `apply(inv(A), g, p)` as a replacement.

docs/src/interface.md

@@ -24,39 +24,65 @@ LieGroups.HasRightInvariantMetric
 ## Functions on Lie Groups
 
 ```@docs
+adjoint
+adjoint!
 base_manifold
 compose
 compose!
-compose_diff_left
-compose_diff_left!
-compose_diff_right
-compose_diff_right!
-compose_inv_left
-compose_inv_left!
-compose_inv_right
-compose_inv_right!
+diff_left_compose
+diff_left_compose!
+diff_right_compose
+diff_right_compose!
+inv_left_compose
+inv_left_compose!
+inv_right_compose
+inv_right_compose!
 conjugate
 conjugate!
+diff_conjugate
+diff_conjugate!
 exp
 exp!
 identity_element
 identity_element!
 is_identity
-inv
+inv(::LieGroup, ::Any)
 inv!
-inv_diff
-inv_diff!
+diff_inv
+diff_inv!
 log
 log!
 ```
 
-## Actions on Lie Groups
+## Actions on Lie groups
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["group_action_interface.jl"]
+Order = [:type]
+```
+
+### Functions for Lie group actions
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["group_action_interface.jl"]
+Order = [:function]
+```
+
+### Specific Lie group actions
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["group_operation_action.jl"]
+Order = [:type, :function]
+```
 
 ## Functions on Lie Algebras
 
 ```@docs
-Lie_bracket
-Lie_bracket!
+lie_bracket
+lie_bracket!
 ```
 
 ## Specific Group Operations

src/LieGroups.jl

@@ -2,8 +2,14 @@ module LieGroups
 
 using ManifoldsBase, Manifolds
 
+# before removing them from Manifolds.jl – let's for consistency include them here but
+# overwrite them for now. This makes moving away from that (in Manifolds.jl 0.11) here nonbreaking.
+import Manifolds: apply, apply!
+
 include("documentation_glossary.jl")
 include("interface.jl")
+include("group_actions/group_action_interface.jl")
+include("group_actions/group_operation_action.jl")
 include("additive_group_operation.jl")
 
 include("groups/additive.jl")
@@ -13,22 +19,32 @@ export LieGroup, LieAlgebra
 export AbstractGroupOperation, Identity
 export AdditiveGroupOperation
 
+export AbstractGroupActionType, AbstractGroupAction
+export AbstractLeftGroupActionType, AbstractRightGroupActionType
+export LeftGroupOperation, RightGroupOperation
+export InverseLeftGroupOperation, InverseRightGroupOperation
+export GroupOperationAction
+
 export AdditiveGroup
 
+export apply, apply!, diff_apply, diff_apply!
 export base_manifold
-export compose,
+export adjoint,
+    adjoint!,
+    compose,
     compose!,
-    compose_diff_left,
-    compose_diff_left!,
-    compose_diff_right,
-    compose_diff_right!,
-    compose_inv_left,
-    compose_inv_left!,
-    compose_inv_right,
-    compose_inv_right!,
-    conjugate,
-    conjugate!
+    diff_left_compose,
+    diff_left_compose!,
+    diff_right_compose,
+    diff_right_compose!,
+    inv_left_compose,
+    inv_left_compose!,
+    inv_right_compose,
+    inv_right_compose!
+export conjugate, conjugate!, diff_conjugate, diff_conjugate!
 export exp, exp!, log, log!
-export identity_element, identity_element!, is_identity, inv, inv!, inv_diff, inv_diff!
-export Lie_bracket, Lie_bracket!
+export identity_element, identity_element!, is_identity, inv, inv!, diff_inv, diff_inv!
+export base_Lie_group, base_manifold
+export lie_bracket, lie_bracket!
+export inv
 end # module LieGroups

src/documentation_glossary.jl

@@ -56,6 +56,7 @@ define!(:LaTeX, :bigr, raw"\bigr")
 define!(:LaTeX, :Big, raw"\Big")
 define!(:LaTeX, :Bigl, raw"\Bigl")
 define!(:LaTeX, :Bigr, raw"\Bigr")
+define!(:LaTeX, :def, raw"\coloneqq")
 define!(:LaTeX, :Cal, (letter) -> raw"\mathcal " * "$letter")
 define!(:LaTeX, :exp, raw"\exp")
 define!(:LaTeX, :Frak, (letter) -> raw"\mathfrak " * "$letter")
@@ -69,12 +70,15 @@ define!(:LaTeX, :rm, (letter) -> raw"\mathrm " * "$letter")
 # :symbol the symbol,
 # :description the description
 _math(args...; kwargs...) = glossary(:Math, args...; kwargs...)
+define!(:Math, :Adjoint, :symbol, raw"\mathrm{Ad}")
+define!(:Math, :Adjoint, :descrption, "the adjoint operation")
+define!(:Math, :Ad, _math(:Adjoint, :symbol))
 define!(:Math, :GroupAction, :symbol, "⋅")
 define!(:Math, :GroupAction, :descrption, "a Lie Group Action")
 define!(:Math, :act, _math(:GroupAction, :symbol))
 define!(:Math, :GroupOp, :symbol, "∘")
 define!(:Math, :GroupOp, :descrption, "the Lie Group operation")
-define!(:Math, :op, _math(:GroupOp, :symbol))
+define!(:Math, :∘, _math(:GroupOp, :symbol))
 define!(:Math, :e, _tex(:rm, "e"))
 define!(:Math, :LieAlgebra, :symbol, (; g="g") -> _tex(:Frak, g))
 define!(:Math, :LieAlgebra, :descrption, "the ie Algebra")
@@ -98,3 +102,37 @@ define!(
     "[`AbstractManifold`](@extref `ManifoldsBase.AbstractManifold`)",
 )
 define!(:Link, :TangentSpace, "[`TangentSpace`](@extref `ManifoldsBase.TangentSpace`)")
+
+#
+# ---
+# Links
+# Collect certain formulae, short texts or even admonitions
+_note(args...; kwargs...) = glossary(:Note, args...; kwargs...)
+
+define!(
+    :Note,
+    :LeftInverseActionIsRight,
+    """
+    ```math
+    τ_g(τ_h(p))
+    = σ^{$(_tex(:rm,"L"))}_{g^{-1}}(σ^{$(_tex(:rm,"L"))}_{h^{-1}}(p))
+    = σ^{$(_tex(:rm,"L"))}_{g^{-1}h^{-1}}(p)
+    = σ^{$(_tex(:rm,"L"))}_{(hg)^{-1}}(p)
+    τ_{hg}(p).
+    ```
+    """,
+)
+
+define!(
+    :Note,
+    :RightInverseActionIsLeft,
+    """
+    ```math
+    τ_g(τ_h(p))
+    = σ^{$(_tex(:rm,"R"))}_{g^{-1}}(σ^{$(_tex(:rm,"R"))}_{h^{-1}}(p))
+    = σ^{$(_tex(:rm,"R"))}_{h^{-1}g^{-1}}(p)
+    = σ^{$(_tex(:rm,"R"))}_{(gh)^{-1}}(p)
+    τ_{gh}(p).
+    ```
+    """,
+)