lie_bracket and adjoint_action

src/groups/special_euclidean.jl

@@ -417,6 +417,15 @@ function group_log!(G::SpecialEuclidean{3}, X, q)
     return X
 end
 
+"""
+    lie_bracket(G::SpecialEuclidean, X::ProductRepr, Y::ProductRepr)
+    lie_bracket(G::SpecialEuclidean, X::AbstractMatrix, Y::AbstractMatrix)
+
+Calculate the Lie bracket between elements `X` and `Y` of the special Euclidean Lie
+algebra. For the matrix representation (which can be obtained using [`screw_matrix`](@ref))
+the formula is ``[X, Y] = XY-YX``, while in the [`ProductRepr`](@ref) representation the
+formula reads ``[X, Y] = [(t_1, R_1), (t_2, R_2)] = (R_1 t_2 - R_2 t_1, R_1 R_2 - R_2 R_1)``.
+"""
 function lie_bracket(G::SpecialEuclidean, X::ProductRepr, Y::ProductRepr)
     nX, hX = submanifold_components(G, X)
     nY, hY = submanifold_components(G, Y)
@@ -494,10 +503,24 @@ const SE_in_GL = EmbeddedManifold{ℝ,<:SpecialEuclidean,<:GeneralLinear}
 
 SE_in_GL(n) = EmbeddedManifold(SpecialEuclidean(n), GeneralLinear(n + 1))
 
+"""
+    embed(M::SE_in_GL, p)
+
+Embed the point `p` on [`SpecialEuclidean`](@ref) in the [`GeneralLinear`](@ref) group.
+The embedding is calculated using [`affine_matrix`](@ref).
+"""
 function embed(M::SE_in_GL, p)
     G = M.manifold
     return affine_matrix(G, p)
 end
+"""
+    embed(M::SE_in_GL, p, X)
+
+Embed the tangent vector X at point `p` on [`SpecialEuclidean`](@ref) in the
+[`GeneralLinear`](@ref) group. Point `p` can use any representation valid for
+`SpecialEuclidean`. The embedding is similar from the one defined by [`screw_matrix`](@ref)
+but the translation part is multiplied by inverse of the rotation part.
+"""
 function embed(M::SE_in_GL, p, X)
     G = M.manifold
     np, hp = submanifold_components(G, p)
@@ -517,11 +540,24 @@ function embed!(M::SE_in_GL, Y, p, X)
     return copyto!(Y, embed(M, p, X))
 end
 
+"""
+    project(M::SE_in_GL, p)
+
+Project point `p` in [`GeneralLinear`](@ref) to the [`SpecialEuclidean`](@ref) group.
+This is performed by extracting the rotation and translation part as in [`affine_matrix`](@ref).
+"""
 function project(M::SE_in_GL, p)
     G = M.manifold
     np, hp = submanifold_components(G, p)
     return ProductRepr(np, hp)
 end
+"""
+    project(M::SE_in_GL, p, X)
+
+Project tangent vector `X` at point `p` in [`GeneralLinear`](@ref) to the
+[`SpecialEuclidean`](@ref) Lie algebra.
+This reverses the transformation performed by [`embed`](@ref embed(M::SE_in_GL, p, X))
+"""
 function project(M::SE_in_GL, p, X)
     G = M.manifold
     np, hp = submanifold_components(G, p)

src/manifolds/ConnectionManifold.jl

@@ -123,6 +123,11 @@ end
     kwargs...,
 )
 
+"""
+    connection(M::ConnectionManifold)
+
+Return the connection associated with [`ConnectionManifold`](@ref) `M`.
+"""
 connection(M::ConnectionManifold) = M.connection
 
 Base.copyto!(M::AbstractConnectionManifold, q, p) = copyto!(M.manifold, q, p)
@@ -158,6 +163,7 @@ end
     gaussian_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = diff_backend())
 
 Compute the Gaussian curvature of the manifold `M` at the point `p` using basis `B`.
+This is equal to half of the scalar Ricci curvature, see [`ricci_curvature`](@ref).
 """
 gaussian_curvature(::AbstractManifold, ::Any, ::AbstractBasis)
 function gaussian_curvature(M::AbstractManifold, p, B::AbstractBasis; kwargs...)
@@ -190,6 +196,12 @@ end
     ricci_curvature(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = diff_backend())
 
 Compute the Ricci scalar curvature of the manifold `M` at the point `p` using basis `B`.
+The curvature is computed as the trace of the Ricci curvature tensor with respect to
+the metric, that is ``R=g^{ij}_R_{ij}`` where ``R`` is the scalar Ricci curvature at `p`,
+``g^{ij}`` is the inverse local metric (see [`inverse_local_metric`](@ref)) at `p` and
+``R_{ij}`` is the Riccie curvature tensor, see [`ricci_tensor`](@ref). Both the tensor and
+inverse local metric are expressed in local coordinates defined by `B`, and the formula
+uses the Einstein summation convention.
 """
 ricci_curvature(::AbstractManifold, ::Any, ::AbstractBasis)
 function ricci_curvature(
@@ -215,7 +227,7 @@ end
 
 Compute the Ricci tensor, also known as the Ricci curvature tensor,
 of the manifold `M` at the point `p` using basis `B`,
-see [https://en.wikipedia.org/wiki/Ricci_curvature#Introduction_and_local_definition](https://en.wikipedia.org/wiki/Ricci_curvature#Introduction_and_local_definition).
+see [`https://en.wikipedia.org/wiki/Ricci_curvature#Introduction_and_local_definition`](https://en.wikipedia.org/wiki/Ricci_curvature#Introduction_and_local_definition).
 """
 ricci_tensor(::AbstractManifold, ::Any, ::AbstractBasis)
 function ricci_tensor(M::AbstractManifold, p, B::AbstractBasis; kwargs...)
@@ -233,11 +245,19 @@ end
 )
 
 @doc raw"""
-    riemann_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend = diff_backend())
+    riemann_tensor(M::AbstractManifold, p, B::AbstractBasis; backend::AbstractDiffBackend=diff_backend())
 
 Compute the Riemann tensor ``R^l_{ijk}``, also known as the Riemann curvature
-tensor, at the point `p`. The dimensions of the resulting multi-dimensional
-array are ordered ``(l,i,j,k)``.
+tensor, at the point `p` in local coordinates defined by `B`. The dimensions of the
+resulting multi-dimensional array are ordered ``(l,i,j,k)``.
+
+The function uses the coordinate expression involving the second Christoffel symbol,
+see [`https://en.wikipedia.org/wiki/Riemann_curvature_tensor#Coordinate_expression`](https://en.wikipedia.org/wiki/Riemann_curvature_tensor#Coordinate_expression)
+for details.
+
+# See also
+
+[`christoffel_symbols_second`], [`christoffel_symbols_second_jacobian`]
 """
 riemann_tensor(::AbstractManifold, ::Any, ::AbstractBasis)
 function riemann_tensor(