lie_bracket and adjoint_action

docs/make.jl

@@ -64,8 +64,9 @@ makedocs(
                 "Vector bundle" => "manifolds/vector_bundle.md",
             ],
             "Manifold decorators" => [
-                "Metric manifold" => "manifolds/metric.md",
+                "Connection manifold" => "manifolds/connection.md",
                 "Group manifold" => "manifolds/group.md",
+                "Metric manifold" => "manifolds/metric.md",
             ],
         ],
         "Features on Manifolds" => [

docs/src/manifolds/connection.md

@@ -0,0 +1,39 @@
+# Connection manifold
+
+A connection manifold always consists of a [topological manifold](https://en.wikipedia.org/wiki/Topological_manifold) together with a [connection](https://en.wikipedia.org/wiki/Connection_(mathematics)) $\Gamma$.
+
+However, often there is an implicitly assumed (default) connection, like the [`LeviCivitaConnection`](@ref) connection on a Riemannian manifold.
+It is not necessary to use this decorator if you implement just one (or the first) connection.
+If you later introduce a second, the old (first) connection can be used with the (non [`AbstractConnectionManifold`](@ref)) [`AbstractManifold`](@ref), i.e. without an explicitly stated connection.
+
+This manifold decorator serves two purposes:
+
+1. to implement different connections (e.g. in closed form) for one [`AbstractManifold`](@ref)
+2. to provide a way to compute geodesics on manifolds, where this [`AbstractAffineConnection`](@ref) does not yield a closed formula.
+
+An example of usage can be found in Cartan-Schouten connections, see [`AbstractCartanSchoutenConnection`](@ref).
+
+```@contents
+Pages = ["connection.md"]
+Depth = 2
+```
+
+## Types
+
+```@autodocs
+Modules = [Manifolds, ManifoldsBase]
+Pages = ["manifolds/ConnectionManifold.jl"]
+Order = [:type]
+```
+
+## Functions
+
+```@autodocs
+Modules = [Manifolds, ManifoldsBase]
+Pages = ["manifolds/ConnectionManifold.jl"]
+Order = [:function]
+```
+
+## [Charts and bases of vector spaces](@id connections_charts)
+
+All connection-related functions take a basis of a vector space as one of the arguments. This is needed because generally there is no way to define these functions without referencing a basis. In some cases there is no need to be explicit about this basis, and then for example a [`DefaultOrthonormalBasis`](@ref) object can be used. In cases where being explicit about these bases is needed, for example when using multiple charts, a basis can be specified, for example using [`induced_basis`](@ref Main.Manifolds.induced_basis).

docs/src/manifolds/group.md

@@ -4,16 +4,28 @@ Lie groups, groups that are [`AbstractManifold`](@ref)s with a smooth binary gro
 
 The common addition and multiplication group operations of [`AdditionOperation`](@ref) and [`MultiplicationOperation`](@ref) are provided, though their behavior may be customized for a specific group.
 
+There are short introductions at the beginning of each subsection. They briefly mention what is available with links to more detailed descriptions.
+
 #### Contents
+
 ```@contents
 Pages = ["group.md"]
 Depth = 3
 ```
 
 ## Groups
 
+The following operations are available for group manifolds:
+
+* [`identity`](@ref): get the identity of the group.
+* [`inv`](@ref): get the inverse of a given element.
+* [`compose`](@ref): compose two given elements of a group.
+
 ### Group manifold
 
+[`GroupManifold`](@ref) adds a group structure to the wrapped manifold.
+It does not affect metric (or connection) structure of the wrapped manifold, however it can to be further wrapped in [`MetricManifold`](@ref) to get invariant metrics, or in a [`ConnectionManifold`](@ref) to equip it with a Cartan-Schouten connection.
+
 ```@autodocs
 Modules = [Manifolds]
 Pages = ["groups/group.jl"]
@@ -86,6 +98,29 @@ Order = [:type, :function]
 
 ## Group actions
 
+Group actions represent actions of a given group on a specified manifold.
+The following operations are available:
+
+* [`apply`](@ref): performs given action of an element of the group on an object of compatible type.
+* [`apply_diff`](@ref): differential of [`apply`](@ref) with respect to the object it acts upon.
+* [`direction`](@ref): tells whether a given action is [`LeftAction`](@ref) or [`RightAction`](@ref).
+* [`inverse_apply`](@ref): performs given action of the inverse of an element of the group on an object of compatible type. By default inverts the element and calls [`apply`](@ref) but it may be have a faster implementation for some actions.
+* [`inverse_apply_diff`](@ref): counterpart of [`apply_diff`](@ref) for [`inverse_apply`](@ref).
+* [`optimal_alignment`](@ref): determine the element of a group that, when it acts upon a point, produces the element closest to another given point in the metric of the G-manifold.
+
+Furthermore, group operation action features the following:
+
+* [`translate`](@ref Main.Manifolds.translate): an operation that performs either left ([`LeftAction`](@ref)) or right ([`RightAction`](@ref)) translation. This is by default performed by calling [`compose`](@ref) with appropriate order of arguments. This function is separated from `compose` mostly to easily represent its differential, [`translate_diff`](@ref).
+* [`translate_diff`](@ref): differential of [`translate`](@ref Main.Manifolds.translate) with respect to the point being translated.
+* [`adjoint_action`](@ref): adjoint action of a given element of a Lie group on an element of its Lie algebra.
+* [`lie_bracket`](@ref): Lie bracket of two vectors from a Lie algebra corresponding to a given group.
+
+The following group actions are available:
+
+* Group operation action [`GroupOperationAction`](@ref) that describes action of a group on itself.
+* [`RotationAction`](@ref), that is action of [`SpecialOrthogonal`](@ref) group on different manifolds.
+* [`TranslationAction`](@ref), which is the action of [`TranslationGroup`](@ref) group on different manifolds.
+
 ```@autodocs
 Modules = [Manifolds]
 Pages = ["groups/group_action.jl"]
@@ -123,3 +158,11 @@ Modules = [Manifolds]
 Pages = ["groups/metric.jl"]
 Order = [:type, :function]
 ```
+
+## Cartan-Schouten connections
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["groups/connections.jl"]
+Order = [:type, :function]
+```

docs/src/manifolds/metric.md

@@ -17,6 +17,8 @@ Pages = ["metric.md"]
 Depth = 2
 ```
 
+Note that a metric manifold is an [`AbstractConnectionManifold`](@ref) with the [`LeviCivitaConnection`](@ref) of the metric $g$, and thus a large part of metric manifold's functionality relies on this.
+
 Let's first look at the provided types.
 
 ## Types
@@ -47,6 +49,6 @@ Order = [:function]
 
 ## Metrics, charts and bases of vector spaces
 
-All metric-related functions take a basis of a vector space as one of the arguments. This needed because generally there is no way to define these functions without referencing a basis. In some cases there is no need to be explicit about this basis, and then for example a [`DefaultOrthonormalBasis`](@ref) object can be used. In cases where being explicit about these bases is needed, for example when using multiple charts, a basis can be specified, for example using [`induced_basis`](@ref Main.Manifolds.induced_basis).
+Metric-related functions, similarly to connection-related functions, need to operate in a basis of a vector space, see [here](@ref connections_charts).
 
 Metric-related functions can take bases of associated tangent spaces as arguments. For example [`local_metric`](@ref) can take the basis of the tangent space it is supposed to operate on instead of a custom basis of the space of symmetric bilinear operators.

docs/src/misc/notation.md

@@ -10,6 +10,7 @@ Within the documented functions, the utf8 symbols are used whenever possible, as
 | Symbol | Description | Also used | Comment |
 |:--:|:--------------- |:--:|:-- |
 | ``\tau_p`` | action map by group element ``p`` | ``\mathrm{L}_p``, ``\mathrm{R}_p`` | either left or right |
+| ``\operatorname{Ad}_p(X)`` | adjoint action of element ``p`` of a Lie group on the element ``X`` of the corresponding Lie algebra | | |
 | ``\times`` | Cartesian product of two manifolds | | see [`ProductManifold`](@ref) |
 | ``^{\wedge}`` | (n-ary) Cartesian power of a manifold | | see [`PowerManifold`](@ref) |
 | ``a`` | coordinates of a point in a chart | | see [`get_parameters`](@ref) |

src/Manifolds.jl

@@ -149,6 +149,8 @@ include("manifolds/VectorBundle.jl")
 include("distributions.jl")
 include("projected_distribution.jl")
 
+include("manifolds/ConnectionManifold.jl")
+
 # It's included early to ensure visibility of `Identity`
 include("groups/group.jl")
 
@@ -195,6 +197,7 @@ include("manifolds/Multinomial.jl")
 include("manifolds/Oblique.jl")
 include("manifolds/EssentialManifold.jl")
 
+include("groups/connections.jl")
 include("groups/metric.jl")
 include("groups/group_action.jl")
 include("groups/group_operation_action.jl")
@@ -352,6 +355,10 @@ export AbstractVectorTransportMethod,
 export PoleLadderTransport, SchildsLadderTransport
 export PowerVectorTransport, ProductVectorTransport
 export AbstractEmbeddedManifold
+export AbstractAffineConnection,
+    AbstractConnectionManifold, ConnectionManifold, LeviCivitaConnection
+export AbstractCartanSchoutenConnection,
+    CartanSchoutenMinus, CartanSchoutenPlus, CartanSchoutenZero
 export AbstractMetric,
     RiemannianMetric,
     LorentzMetric,
@@ -528,7 +535,9 @@ export AbstractGroupAction,
     SpecialOrthogonal,
     TranslationGroup,
     TranslationAction
-export affine_matrix,
+export adjoint_action,
+    adjoint_action!,
+    affine_matrix,
     apply,
     apply!,
     apply_diff,
@@ -559,6 +568,8 @@ export affine_matrix,
     inverse_translate!,
     inverse_translate_diff,
     inverse_translate_diff!,
+    lie_bracket,
+    lie_bracket!,
     make_identity,
     optimal_alignment,
     optimal_alignment!,

src/groups/array_manifold.jl

@@ -4,6 +4,24 @@ array_point(p) = ValidationMPoint(p)
 array_point(p::ValidationMPoint) = p
 array_point(e::Identity) = Identity(e.group, array_point(e.p))
 
+function adjoint_action(M::ValidationManifold, p, X; kwargs...)
+    is_point(M, p, true; kwargs...)
+    eM = make_identity(M.manifold, array_value(p))
+    is_vector(M, eM, X, true; kwargs...)
+    Y = ValidationTVector(adjoint_action(M.manifold, array_value(p), array_value(X)))
+    is_vector(M, eM, Y, true; kwargs...)
+    return Y
+end
+
+function adjoint_action!(M::ValidationManifold, Y, p, X; kwargs...)
+    is_point(M, p, true; kwargs...)
+    eM = make_identity(M.manifold, array_value(p))
+    is_vector(M, eM, X, true; kwargs...)
+    adjoint_action!(M.manifold, array_value(Y), array_value(p), array_value(X))
+    is_vector(M, eM, Y, true; kwargs...)
+    return Y
+end
+
 function Base.inv(M::ValidationManifold, p; kwargs...)
     is_point(M, p, true; kwargs...)
     q = array_point(inv(M.manifold, array_value(p)))
@@ -32,6 +50,24 @@ function identity!(M::ValidationManifold, q, p; kwargs...)
     return q
 end
 
+function lie_bracket(M::ValidationManifold, X, Y)
+    eM = make_identity(M.manifold, array_value(X))
+    is_vector(M, eM, X, true)
+    is_vector(M, eM, Y, true)
+    Z = ValidationTVector(lie_bracket(M.manifold, array_value(X), array_value(Y)))
+    is_vector(M, eM, Z, true)
+    return Z
+end
+
+function lie_bracket!(M::ValidationManifold, Z, X, Y)
+    eM = make_identity(M.manifold, array_value(X))
+    is_vector(M, eM, X, true)
+    is_vector(M, eM, Y, true)
+    lie_bracket!(M.manifold, array_value(Z), array_value(X), array_value(Y))
+    is_vector(M, eM, Z, true)
+    return Z
+end
+
 function compose(M::ValidationManifold, p, q; kwargs...)
     is_point(M, p, true; kwargs...)
     is_point(M, q, true; kwargs...)

src/groups/circle_group.jl

@@ -14,6 +14,10 @@ invariant_metric_dispatch(::CircleGroup, ::ActionDirection) = Val(true)
 
 default_metric_dispatch(::MetricManifold{ℂ,CircleGroup,EuclideanMetric}) = Val(true)
 
+adjoint_action(::CircleGroup, p, X) = X
+
+adjoint_action!(::CircleGroup, Y, p, X) = copyto!(Y, X)
+
 function compose(G::CircleGroup, p::AbstractVector, q::AbstractVector)
     return map(compose, repeated(G), p, q)
 end
@@ -46,6 +50,10 @@ function inverse_translate(
     return map(/, q, p)
 end
 
+lie_bracket(::CircleGroup, X, Y) = zero(X)
+
+lie_bracket!(::CircleGroup, Z, X, Y) = fill!(Z, 0)
+
 translate_diff(::GT, p, q, X, ::ActionDirection) where {GT<:CircleGroup} = map(*, p, X)
 function translate_diff(
     ::GT,