From 697df39f7fd15f6484b10265e7592d2ee64cb703 Mon Sep 17 00:00:00 2001 From: Mateusz Baran Date: Mon, 23 Oct 2023 11:09:52 +0200 Subject: [PATCH] docs improvements; split group actions to a separate page --- docs/make.jl | 1 + docs/src/features/group_actions.md | 63 ++++++++++++++++++++++ docs/src/manifolds/group.md | 66 +---------------------- src/Manifolds.jl | 1 + src/groups/group_operation_action.jl | 2 +- src/groups/rotation_action.jl | 2 +- src/groups/rotation_translation_action.jl | 7 +++ 7 files changed, 75 insertions(+), 67 deletions(-) create mode 100644 docs/src/features/group_actions.md diff --git a/docs/make.jl b/docs/make.jl index 8dfca558e6..7d3b3a66ee 100755 --- a/docs/make.jl +++ b/docs/make.jl @@ -155,6 +155,7 @@ makedocs(; "Atlases and charts" => "features/atlases.md", "Differentiation" => "features/differentiation.md", "Distributions" => "features/distributions.md", + "Group actions" => "features/group_actions.md", "Integration" => "features/integration.md", "Statistics" => "features/statistics.md", "Testing" => "features/testing.md", diff --git a/docs/src/features/group_actions.md b/docs/src/features/group_actions.md new file mode 100644 index 0000000000..22bf676ba9 --- /dev/null +++ b/docs/src/features/group_actions.md @@ -0,0 +1,63 @@ +# Group actions + +Group actions represent actions of a given group on a specified manifold. +The following operations are available: + +* [`action_side`](@ref): whether action acts from the [`LeftSide`](@ref) or [`RightSide`](@ref) (not to be confused with action direction). +* [`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), [`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 ([`LeftAction`](@ref)) on the [`LeftSide`](@ref) or ([`RightAction`](@ref)) on the [`RightSide`](@ref) translation, or actions by inverses of elements ([`RightAction`](@ref) on the [`LeftSide`](@ref) and [`LeftAction`](@ref) on the [`RightSide`](@ref)). 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"] +Order = [:type, :function] +``` + +## Group operation action + +```@autodocs +Modules = [Manifolds] +Pages = ["groups/group_operation_action.jl"] +Order = [:type, :function] +``` + +## Rotation action + +```@autodocs +Modules = [Manifolds] +Pages = ["groups/rotation_action.jl"] +Order = [:type, :function] +``` + +## Translation action + +```@autodocs +Modules = [Manifolds] +Pages = ["groups/translation_action.jl"] +Order = [:type, :function] +``` + +## Rotation-translation action (special Euclidean) + +```@autodocs +Modules = [Manifolds] +Pages = ["groups/rotation_translation_action.jl"] +Order = [:type, :const, :function] +``` diff --git a/docs/src/manifolds/group.md b/docs/src/manifolds/group.md index 78d7593db4..c7c328fcf2 100644 --- a/docs/src/manifolds/group.md +++ b/docs/src/manifolds/group.md @@ -1,4 +1,4 @@ -# [Group manifolds and actions](@id GroupManifoldSection) +# [Group manifolds](@id GroupManifoldSection) Lie groups, groups that are Riemannian manifolds with a smooth binary group operation [`AbstractGroupOperation`](@ref), are implemented as [`AbstractDecoratorManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/decorator.html#ManifoldsBase.AbstractDecoratorManifold) and specifying the group operation using the [`IsGroupManifold`](@ref) or by decorating an existing manifold with a group operation using [`GroupManifold`](@ref). @@ -180,70 +180,6 @@ Pages = ["groups/translation_group.jl"] Order = [:constant, :type, :function] ``` -## Group actions - -Group actions represent actions of a given group on a specified manifold. -The following operations are available: - -* [`action_side`](@ref): whether action acts from the [`LeftSide`](@ref) or [`RightSide`](@ref) (not to be confused with action direction). -* [`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), [`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 ([`LeftAction`](@ref)) on the [`LeftSide`](@ref) or ([`RightAction`](@ref)) on the [`RightSide`](@ref) translation, or actions by inverses of elements ([`RightAction`](@ref) on the [`LeftSide`](@ref) and [`LeftAction`](@ref) on the [`RightSide`](@ref)). 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"] -Order = [:type, :function] -``` - -### Group operation action - -```@autodocs -Modules = [Manifolds] -Pages = ["groups/group_operation_action.jl"] -Order = [:type, :function] -``` - -### Rotation action - -```@autodocs -Modules = [Manifolds] -Pages = ["groups/rotation_action.jl"] -Order = [:type, :function] -``` - -### Translation action - -```@autodocs -Modules = [Manifolds] -Pages = ["groups/translation_action.jl"] -Order = [:type, :function] -``` - -### Rotation-translation action (special Euclidean) - -```@autodocs -Modules = [Manifolds] -Pages = ["groups/rotation_translation_action.jl"] -Order = [:type, :function] -``` - ## Metrics on groups Lie groups by default typically forward all metric-related operations like exponential or logarithmic map to the underlying manifold, for example [`SpecialOrthogonal`](@ref) uses methods for [`Rotations`](@ref) (which is, incidentally, bi-invariant), or [`SpecialEuclidean`](@ref) uses product metric of the translation and rotation parts (which is not invariant under group operation). diff --git a/src/Manifolds.jl b/src/Manifolds.jl index bce05384dd..e56361fcac 100644 --- a/src/Manifolds.jl +++ b/src/Manifolds.jl @@ -932,6 +932,7 @@ export AbstractGroupAction, RightSide, RotationAction, RotationTranslationAction, + RotationTranslationActionOnVector, SemidirectProductGroup, SpecialEuclidean, SpecialLinear, diff --git a/src/groups/group_operation_action.jl b/src/groups/group_operation_action.jl index 87b3585581..34e6de888c 100644 --- a/src/groups/group_operation_action.jl +++ b/src/groups/group_operation_action.jl @@ -6,7 +6,7 @@ An element `p` of the group can act upon another another element by either: * left action from the left side: ``L_p: q ↦ p \circ q``, * right action from the left side: ``L'_p: q ↦ p^{-1} \circ q``, * right action from the right side: ``R_p: q ↦ q \circ p``, -* left action from the right side: ``R'_p &: q ↦ q \circ p^{-1}``. +* left action from the right side: ``R'_p: q ↦ q \circ p^{-1}``. # Constructor diff --git a/src/groups/rotation_action.jl b/src/groups/rotation_action.jl index 25f211177b..cebd3016a4 100644 --- a/src/groups/rotation_action.jl +++ b/src/groups/rotation_action.jl @@ -274,7 +274,7 @@ of computation are described in Section 2.2.1 of [SrivastavaKlassen:2016](@cite) The formula reads ```math O^{*} = \begin{cases} -UV^T & \text{if } \operatorname{det}(p q^{\mathrm{T}})\\ +UV^T & \text{if } \operatorname{det}(p q^{\mathrm{T}}) \geq 0\\ U K V^{\mathrm{T}} & \text{otherwise} \end{cases} ``` diff --git a/src/groups/rotation_translation_action.jl b/src/groups/rotation_translation_action.jl index 485879cb77..ea706e3639 100644 --- a/src/groups/rotation_translation_action.jl +++ b/src/groups/rotation_translation_action.jl @@ -32,6 +32,13 @@ function Base.show(io::IO, A::RotationTranslationAction) return print(io, "RotationTranslationAction($(A.manifold), $(A.SEn), $(direction(A)))") end +""" + RotationTranslationActionOnVector{TAD,𝔽,TE,TSE} + +Alias for [`RotationTranslationAction`](@ref) where the manifold `M` is [`Euclidean`](@ref) +or [`TranslationGroup`](@ref) with size of type `TE`, and [`SpecialEuclidean`](@ref) +group has size type `TSE`. +""" const RotationTranslationActionOnVector{TAD,𝔽,TE,TSE} = RotationTranslationAction{ TAD, <:Union{Euclidean{TE,𝔽},TranslationGroup{TE,𝔽}},