Transfer more elements from Manifolds.jl (#65)

* add jacobian of the exponential function.
* Fix a merge mistake.
* Improve notation and add a note on left/right Jacobians.
* Fix a note.
* Sketch ColumAction, transfer the LeftMult action of SE(n) onto Rn.
* Finish SE(n) acting on Rn.
* add rotation around axis action
* limit imports from Manifolds
* Introduce types for row and column wise actions as generic wrappers.
* Fix docs.
* runic.
* add tests for row and columnwise actions.
* transfer the last action.
* test coverage I
* propose a different way of transferring the jacobian of the exponential.
* Fix docs.
* Bump version, set today as release day.

---------

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

Author: kellertuer

NEWS.md

@@ -5,15 +5,19 @@ All notable Changes to the Julia package `LieGroups.jl` will be documented in th
 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.1.4] unreleased
+## [0.1.4] 2025-10-02
 
 ### Added
 
+* mention `adjoint_matrix` in the transition documentation (#52)
+* introduce `jacobian_exp` for the Jacobian of the exponential function.
 * Introduce a `AbstractActionActsOnType` to distinguish, what previously was called “side”,
   i.e. whether an action acts on the left (`ActionActsOnLeft`) or right (`ActionActsOnRight`)
 * Introduce `_inv` and `_inv!` functions for the inverse operation to work the same way as `_compose` and `_compose!`, respectively.
 * introduce a `LeftMultiplicationGroupAction` to represent left multiplication actions on Lie groups. While this is a bit more of a technical
   name, it replaces the old `ComplexPlanarRotation`, `QuaternionRotation`, and `RotationAction`, since in the `GroupAction` this type is coupled with a group and a manifold anyway.
+* further methods for the `LeftMultiplicationGroupAction` to cover the previous functionality of e.g.
+  * `RotationTranslationActionOnVector`
 * Add the Special Galilean Group (#60)
 
 ### Fixed
@@ -23,6 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Fixed an issue, where `exp!(G, h, g, X)` would return a wrong result if the input `g`and the output `h`are aliased (#63).
 * Fixed issues with the documentation of `diff_left_compose` and `diff_right_compose` that were inconsistent
 * fixed `push_forward_tangent` and `pull_back_tangent` which on general Lie groups provided a wrong default.
+* fixes an allocation bug for `apply` and `diff_apply` (#52)
+
 
 ## [0.1.3] 2025-08-04
 

Project.toml

@@ -1,7 +1,7 @@
 name = "LieGroups"
 uuid = "6774de46-80ba-43f8-ba42-e41071ccfc5f"
 authors = ["Seth Axen <[email protected]>", "Mateusz Baran <[email protected]>", "Ronny Bergmann <[email protected]>", "Yueh-Hua Tu", "Olivier Verdier <[email protected]>"]
-version = "0.1.3"
+version = "0.1.4"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

docs/src/interface/actions.md

@@ -16,18 +16,42 @@ Order = [:function]
 
 # Generic Lie group actions
 
+```@autodocs
+Modules = [LieGroups]
+Pages = ["addition_action.jl"]
+Order = [:type, :function]
+```
+
 ```@autodocs
 Modules = [LieGroups]
 Pages = ["group_operation_action.jl"]
 Order = [:type, :function]
 ```
 
+```@autodocs
+Modules = [LieGroups]
+Pages = ["columnwise_action.jl"]
+Order = [:type, :function]
+```
+
 ```@autodocs
 Modules = [LieGroups]
 Pages = ["multiplication_action.jl"]
 Order = [:type, :function]
 ```
 
+```@autodocs
+Modules = [LieGroups]
+Pages = ["group_actions/rotation_around_axis_action.jl"]
+Order = [:type, :function]
+```
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["rowwise_action.jl"]
+Order = [:type, :function]
+```
+
 ## Literature
 
 ```@bibliography

docs/src/notation.md

@@ -8,18 +8,49 @@ In this package,the notation introduced in [Manifolds.jl Notation](https://julia
 | ``∘`` | a group operation | | |
 | ``c_g:\mathcal G → \mathcal G`` | the conjugation map (with `g`) | | |
 | ``Df(p)[X]`` | the differential of a map `f` at point `p` in direction `X` | | |
-| ``\mathrm{d}f`` | the differential of a map `f` as a function on the Lie group and the differential on the Lie algebra. | | |
-| ``\mathrm{D}_af`` | the differential of a map `f`. An index is used to indicate a certain parameter. If ``f`` is defined on or maps into the Lie group, this differential indicates the one with respect to tangent spaces  | | |
+| ``\mathrm{d}f`` | the differential of a map `f` as a function on the Lie group and the differential on the Lie algebra. | | see also note below |
+| ``\mathrm{D}_af`` | the differential of a map `f`. An index is used to indicate a certain parameter. If ``f`` is defined on or maps into the Lie group, this differential indicates the one with respect to tangent spaces  | | see also note below|
 | ``\mathrm{e}`` | identity element of a group | | |
 | ``\exp_{\mathcal G}(X)`` | The Lie group exponential function | | |
 | ``\exp_g(X)`` | The Lie group exponential map (w.r.t. a Cartan Schouten connection) | | |
 | ``g, h, k`` | elements on a (Lie) group. Sometimes called points. | ``g_1, g_2, ...`` | |
 | ``\mathfrak g`` | a Lie algebra | | |
 | ``\mathcal{G}`` | a Lie group | | |
+| ``\operatorname{J}_f(p)`` | the Jacobian of a map `f` at point `p` | | sometimes left Jacobian, see note below. |
 | ``λ_g: \mathcal G → \mathcal G`` | the left group operation map ``λ_g(h) = g∘h`` | | |
 | ``\log_{\mathcal G}(g)`` | The Lie group logarithmic function | | |
 | ``\log_g(h)`` | The Lie group logarithmic map (w.r.t. a Cartan Schouten connection) | | |
 | ``α: \mathcal M → \mathcal G → \mathcal M`` | a (general) group action | | |
 | ``ρ_g: \mathcal G → \mathcal G`` | the right group operation map ``ρ_g(h) = h∘g`` | | |
 | ``σ: \mathcal G × \mathcal M → \mathcal M`` | a left group action | | ``σ_g(p)`` to emphasize a fixed group element |
 | ``τ: \mathcal G × \mathcal M → \mathcal M`` | a right group action | ``σ_\mathrm{R}`` | ``τ_g(p)`` to emphasize a fixed group element |
+
+## About differentials and Jacobians
+
+For a function defined on a [manifold](@extref `ManifoldsBase.AbstractManifold`) ``f:\mathcal M → \mathcal N``, the differential at a point ``p ∈ \mathcal M`` is a map between the tangent spaces
+
+```math
+Df(p) : T_p\mathcal M → T_{f(p)}\mathcal N.
+```
+
+This is the default in  [`Manifolds.jl`](@extref Manifolds :std:doc:`index`).
+
+For the case where ``\mathcal M = \mathcal N = \mathcal G`` is an [`AbstractLieGroup`](@ref), the differential can be expressed in terms of the Lie algebra ``\mathfrak g`` as
+
+```math
+\mathrm{d}f(g) : \mathfrak g → \mathfrak g.
+```
+
+An alternate way to define this differential on the Lie algebra is to consider the (usual) differential ``Dg(p)`` of ``g(q) = f(q⋅p)⋅f(p)^{-1}``.
+
+where we use a different notation on purpose. This second notation is the default throughout `LieGroups.jl`.
+
+The Jacobian ``\operatorname{J}_f(p)`` of ``f`` at ``p`` is the matrix representation of the differential with respect to a basis of each of the tangent spaces.
+For the default representation ``\mathrm{d}f(g)`` we have to choose a basis of the [Lie algebra](@ref LieAlgebra) ``\mathfrak g``.
+Throughout `LieGroups.jl` this is the [`DefaultLieAlgebraOrthogonalBasis`](@ref).
+
+## About left and right Jacobians
+
+This jacobian using ``\mathrm{d}f(g)`` and the [`DefaultLieAlgebraOrthogonalBasis`](@ref) is sometimes called the left Jacobian.
+The other choice using on two tangent space bases of ``T_p\mathcal G`` and ``T_{f(p)}\mathcal G``, respectively, is sometimes called the right Jacobian.
+The default throughout `LieGroups.jl` is the left Jacobian.

docs/src/references.bib

@@ -34,6 +34,21 @@ @book{BinzPods:2008
     YEAR = {2008}
 }
 
+#
+#
+# C
+# ------------------------------------------------------------------------------------------
+@book{Chirikjian:2012,
+	edition = {1},
+	series = {Applied and {Numerical} {Harmonic} {Analysis}},
+	title = {Stochastic {Models}, {Information} {Theory}, and {Lie} {Groups}, {Volume} 2},
+	volume = {2},
+	url = {https://link.springer.com/book/10.1007/978-0-8176-4944-9},
+	publisher = {Birkhäuser Boston, MA},
+	author = {Chirikjian, Gregory S.},
+	year = {2012},
+}
+
 #
 #
 # G

docs/src/tutorials/transition.md

@@ -17,11 +17,13 @@ Lie algebra elements (vectors) always `X, Y`.
 
 New functions and types in this package are only mentioned, if they are worth a comment and if something changed.
 
-The list is alphabetical, but first lists types, then functions
+The list lists first types, then functions. Within both blocks, the order is alphabetical
 
 | `Manifolds.jl` | `LieGroups.jl` | Comment |
 |:---------- |:---------- |:-------------- |
 | `AdditionOperation` | [`AdditionGroupOperation`](@ref) | |
+| `ColumnwiseMultiplicationAction` | [`ColumnwiseGroupAction`](@ref)`(`[`LeftMultiplicationGroupAction`](@ref)`)` | within a [`GroupAction`](@ref)`(action, group, manifold)` |
+| `ColumnwiseSpecialEuclideanAction` |  [`ColumnwiseGroupAction`](@ref)`(`[`LeftMultiplicationGroupAction`](@ref)`)` | within a [`GroupAction`](@ref)`(action, group, manifold)`, where the `group`is a [`SpecialEuclideanGroup`](@ref) |
 | `ComplexPlanarRotation` | [`LeftMultiplicationGroupAction`](@ref) | a slightly more general type for all actions that are implemented by (matrix) multiplication |
 | `GroupActionSide` | [`AbstractActionActsOnType`](@ref) | Switching to a new, hopefully more descriptive naming. |
 | `LeftBackwardAction` | [`AbstractRightGroupActionType`](@ref) and [`ActionActsOnRight`](@ref) | This tuple form has been discontinued. |
@@ -36,9 +38,14 @@ The list is alphabetical, but first lists types, then functions
 | `RightForwardAction` | [`AbstractRightGroupActionType`](@ref) and [`ActionActsOnLeft`](@ref) | This tuple form has been discontinued. |
 | `RightSide` | [`ActionActsOnRight`](@ref) | |
 | `RotationAction` | [`LeftMultiplicationGroupAction`](@ref) | a slightly more general type for all actions that are implemented by (matrix) multiplication |
+| `RotationTranslationActionOnVector` | [`LeftMultiplicationGroupAction`](@ref) | e.g. in a [`GroupAction`](@ref) with [`SpecialEuclideanGroup`](@ref) and [`Euclidean`](@extref `Manifolds.Euclidean`)`(n)`. |
+| `RowwiseMultiplicationAction` | [`RowwiseGroupAction`](@ref)`(`[`LeftMultiplicationGroupAction`](@ref)`)` | |
 | `SemidirectProductGroup(G, H, a)` | [`LeftSemidirectProductLieGroup`](@ref)`(G, H, a)` | While this staid the same, there is now also the [`default_left_action`](@ref)`(G,H)`. When this agrees with `a` you can use the short hand `G⋉H` to generate this semidirect product. Analogously there now also exists the [`RightSemidirectProductLieGroup`](@ref)`(G,H)` with[`default_left_action`](@ref)`(G,H)` that allows for the short cut `G⋊H` |
 | `SpecialEuclidean(n)` | `SpecialEuclideanGroup(n; variant=:right)` | |
+| `TranslationAction` | [`AdditionGroupAction`](@ref) | this slightly more general name allows to reuse the action in other contexts easier |
+| `VeeOrthogonalBasis` | [`DefaultLieAlgebraOrthogonalBasis`](@ref) | |
 | `adjoint_action` | [`adjoint`](@ref) | now implemented with a default, when you provide [`diff_conjugate!`](@ref).
+| `adjoint_matrix(G, p, b)` | [`jacobian_conjugate`](@ref)`(G, p, e, b)` | `e` is either the [`Identity`](@ref)`(G)` or its [`identity_element`](@ref)`(G)` |
 | `apply_diff` | [`diff_apply`](@ref) | modifiers (diff) come first, consistent with [`ManifoldsDiff.jl`](https://juliamanifolds.github.io/ManifoldDiff.jl/stable/) |
 | `apply_diff_group` | [`diff_group_apply`](@ref) | modifiers (diff/group) come first, consistent with [`ManifoldsDiff.jl`](https://juliamanifolds.github.io/ManifoldDiff.jl/stable/) |
 | | [`conjugate`](@ref), [`diff_conjugate`](@ref) | a new function to model ``c_g: \mathcal G → \mathcal G`` given by ``c_g(h) = g∘h∘g^{-1}`` |
@@ -53,6 +60,7 @@ The list is alphabetical, but first lists types, then functions
 | `inverse_translate(G, g, h, c)` | [`inv_left_compose`](@ref)`(G, g, h)`, [`inv_right_compose`](@ref)`(G, g, h)` | compute ``g^{-1}∘h`` and ``g∘h^{-1}``, resp. |
 | `inverse_translate_diff(G, g, h, X, LeftForwardAction())` | - | discontinued, use `diff_left_compose(G, inv(G,g), h)` |
 | `inverse_translate_diff(G, g, h, X, RightBackwardAction())` | - | discontinued, use `diff_left_compose(G, h, inv(G,g))` |
+| `jacobian_exp_argument(G, g, X, b)` | [`jacobian_exp`](@ref)`(G, g, X, b)` | the Jacobian of the exponential map w.r.t. an [`AbstractBasis`](@extref `ManifoldsBase.AbstractBasis`) of the [`LieAlgebra`](@ref). The old name is resevered for the Riemannian exponential map. |
 | `log(G, g, h)` | `log(`[`base_manifold`](@ref base_manifold(G::LieGroup))`(G), g, h)` | you can now access the previous defaults on the internal manifold whenever they do not agree with the invariant one |
 | `log_inv(G, g, h)` | [`log`](@ref log(G::LieGroup, g, h))`(G, g, h)` | the logarithmic map invariant to the group operation is the default on Lie groups here |
 | `log_lie(G, g)` | [`log`](@ref log(G::LieGroup, g))`(G, g)` | the (matrix/Lie group) logarithm |
@@ -62,7 +70,6 @@ The list is alphabetical, but first lists types, then functions
 | `translate(G, g, h)` | [`compose`](@ref)`(G, g, h)` | unified to `compose` |
 | `translate_diff(G, g, X, c)` | [`diff_left_compose`](@ref)`(G, g, h, X)`, [`diff_right_compose`](@ref)`(G, g, h, X)` | for compose ``g∘h`` the functions now specify whether the derivative is taken w.r.t. to the left (`g`) or right (`h`) argument |
 | `vee(G, p, X)` | [`vee`](@ref vee(G::LieAlgebra, X))`(`[`LieAlgebra`](@ref)`(G), X)` | hat/vee moved to using the new [`LieAlgebra`](@ref). The old format should still work. |
-| `VeeOrthogonalBasis` | [`DefaultLieAlgebraOrthogonalBasis`](@ref) | |
 
 ## Further notable changes
 

ext/LieGroupsRecursiveArrayToolsExt/LieGroupsRecursiveArrayToolsExt.jl

@@ -1,10 +1,13 @@
 module LieGroupsRecursiveArrayToolsExt
 
 using LieGroups
+# As long as Manifolds.jl exports these, we have to specify them here specifically
 using RecursiveArrayTools: ArrayPartition
 using LinearAlgebra
 using ManifoldsBase
 using ManifoldsBase: base_manifold, submanifold_components, submanifold_component
+# Specify those that are imported twice to use the ones from LieGroups
+
 
 include("special_euclidean_group_RAT_ext.jl")
 include("special_galilean_group_RAT_ext.jl")

ext/LieGroupsRecursiveArrayToolsExt/special_euclidean_group_RAT_ext.jl

@@ -1,6 +1,41 @@
 # disable affine check
 LieGroups._check_matrix_affine(::ArrayPartition, ::Int; kwargs...) = nothing
 
+#
+# Action
+#
+
+# (a) SE(n) on R^n
+# Euclidean was imported to LieGroups, so we can access it from there.
+function LieGroups.apply!(
+        ::GroupAction{LeftMultiplicationGroupAction, <:LieGroups.LeftSpecialEuclideanGroup, <:LieGroups.Euclidean}, q, g::ArrayPartition, p
+    )
+    mul!(q, g.x[1], p)
+    q .+= g.x[2]
+    return q
+end
+function LieGroups.apply!(
+        ::GroupAction{LieGroups.LeftMultiplicationGroupAction, <:LieGroups.RightSpecialEuclideanGroup, <:LieGroups.Euclidean}, q, g::ArrayPartition, p
+    )
+    mul!(q, g.x[2], p)
+    q .+= g.x[1]
+    return q
+end
+
+function LieGroups.diff_apply!(
+        ::GroupAction{LieGroups.LeftMultiplicationGroupAction, <:LieGroups.LeftSpecialEuclideanGroup, <:LieGroups.Euclidean},
+        Y, g::ArrayPartition, p, X
+    )
+    mul!(Y, g.x[1], X)
+    return Y
+end
+function LieGroups.diff_apply!(
+        ::GroupAction{LieGroups.LeftMultiplicationGroupAction, <:LieGroups.RightSpecialEuclideanGroup, <:LieGroups.Euclidean},
+        Y, g::ArrayPartition, p, X
+    )
+    mul!(Y, g.x[2], X)
+    return Y
+end
 #
 # Conversions
 #

src/LieGroups.jl

@@ -63,8 +63,13 @@ include("group_operations/multiplication_operation_abelian.jl")
 
 # Actions
 include("group_actions/group_action_interface.jl")
+include("group_actions/addition_action.jl")
 include("group_actions/group_operation_action.jl")
 include("group_actions/multiplication_action.jl")
+include("group_actions/rotation_around_axis_action.jl")
+# These might use some of the above so we include them second
+include("group_actions/columnwise_action.jl")
+include("group_actions/rowwise_action.jl")
 
 # Meta Lie groups
 include("groups/power_group.jl")
@@ -112,15 +117,18 @@ export PowerGroupOperation, ProductGroupOperation
 export LeftSemidirectProductGroupOperation, RightSemidirectProductGroupOperation
 
 #
-#1,
+#
 # Group Actions
 export AbstractGroupActionType
 export AbstractLeftGroupActionType, AbstractRightGroupActionType
+export AdditionGroupAction
 export LeftGroupOperationAction, RightGroupOperationAction
 export GroupAction, GroupOperationAction
 export LeftMultiplicationGroupAction
 export InverseLeftGroupOperationAction, InverseRightGroupOperationAction
 export AbstractActionActsOnType, ActionActsOnLeft, ActionActsOnRight
+export RotationAroundAxisAction
+export ColumnwiseGroupAction, RowwiseGroupAction
 
 #
 #
@@ -170,6 +178,7 @@ export identity_element, identity_element!, is_identity, inner
 export inv, inv!, diff_inv, diff_inv!
 export injectivity_radius
 export jacobian_conjugate, jacobian_conjugate!
+export jacobian_exp, jacobian_exp!
 export lie_bracket, lie_bracket!, log, log!
 export manifold_dimension
 export norm, number_of_coordinates

src/group_actions/addition_action.jl

@@ -0,0 +1,28 @@
+"""
+    AdditionGroupAction <: AbstractLeftGroupActionType
+
+Specify that in a [`GroupAction`](@ref) with Lie group ``$(_tex(:Cal, "G"))``
+and manifold ``$(_tex(:Cal, "M"))``, where the group action is given by addition
+
+Given an element ``g ∈ $(_tex(:Cal, "G"))`` and a point ``p ∈ $(_tex(:Cal, "M"))``,
+the family of actions ``σ_g: $(_tex(:Cal, "M")) → $(_tex(:Cal, "M"))`` is given by
+
+```math
+σ_g(p) = g + p
+```
+
+where ``+`` denotes the vector or matrix addition.
+"""
+struct AdditionGroupAction <: AbstractLeftGroupActionType end
+
+function apply!(::GroupAction{AdditionGroupAction}, q, g, p)
+    return q .= g .+ p
+end
+
+function diff_apply!(::GroupAction{AdditionGroupAction}, Y, g, p, X)
+    return Y .= X
+end
+
+function diff_group_apply!(::GroupAction{AdditionGroupAction}, Y, g, p, X)
+    return Y .= X
+end