Group actions

Group actions represent actions of a given group on a specified manifold. The following operations are available:

action_side: whether action acts from the LeftSide or RightSide (not to be confused with action direction).
apply: performs given action of an element of the group on an object of compatible type.
apply_diff: differential of apply with respect to the object it acts upon.
direction: tells whether a given action is LeftAction, RightAction.
inverse_apply: 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 but it may be have a faster implementation for some actions.
inverse_apply_diff: counterpart of apply_diff for inverse_apply.
optimal_alignment: 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: an operation that performs either (LeftAction) on the LeftSide or (RightAction) on the RightSide translation, or actions by inverses of elements (RightAction on the LeftSide and LeftAction on the RightSide). This is by default performed by calling compose with appropriate order of arguments. This function is separated from compose mostly to easily represent its differential, translate_diff.
translate_diff: differential of translate with respect to the point being translated.
adjoint_action: adjoint action of a given element of a Lie group on an element of its Lie algebra.
lie_bracket: Lie bracket of two vectors from a Lie algebra corresponding to a given group.

The following group actions are available:

Group operation action GroupOperationAction that describes action of a group on itself.
RotationAction, that is action of SpecialOrthogonal group on different manifolds.
TranslationAction, which is the action of TranslationGroup group on different manifolds.

Manifolds.AbstractGroupAction — Type

AbstractGroupAction{AD<:ActionDirection}

An abstract group action on a manifold. ActionDirectionAD indicates whether it is a left or right action.

source

Manifolds.adjoint_apply_diff_group — Method

adjoint_apply_diff_group(A::AbstractGroupAction, a, X, p)

Pullback with respect to group element of group action A.

\[(\mathrm{d}τ^{p,*}) : T_{τ_{a} p} \mathcal M → T_{a} \mathcal G\]

source

Manifolds.apply! — Method

apply!(A::AbstractGroupAction, q, a, p)

Apply action a to the point p with the rule specified by A. The result is saved in q.

source

Manifolds.apply — Method

apply(A::AbstractGroupAction, a, p)

Apply action a to the point p using map $τ_a$, specified by A. Unless otherwise specified, the right action is defined in terms of the left action:

\[\mathrm{R}_a = \mathrm{L}_{a^{-1}}\]

source

Manifolds.apply_diff — Method

apply_diff(A::AbstractGroupAction, a, p, X)

For point $p ∈ \mathcal M$ and tangent vector $X ∈ T_p \mathcal M$, compute the action on $X$ of the differential of the action of $a ∈ \mathcal{G}$, specified by rule A. Written as $(\mathrm{d}τ_a)_p$, with the specified left or right convention, the differential transports vectors

\[(\mathrm{d}τ_a)_p : T_p \mathcal M → T_{τ_a p} \mathcal M\]

source

Manifolds.apply_diff_group — Method

apply_diff_group(A::AbstractGroupAction, a, X, p)

Compute the value of differential of action AbstractGroupAction A on vector X, where element a is acting on p, with respect to the group element.

Let $\mathcal G$ be the group acting on manifold $\mathcal M$ by the action A. The action is of element $g ∈ \mathcal G$ on a point $p ∈ \mathcal M$. The differential transforms vector X from the tangent space at a ∈ \mathcal G, $X ∈ T_a \mathcal G$ into a tangent space of the manifold $\mathcal M$. When action on element p is written as $\mathrm{d}τ^p$, with the specified left or right convention, the differential transforms vectors

\[(\mathrm{d}τ^p) : T_{a} \mathcal G → T_{τ_a p} \mathcal M\]

See also

apply, apply_diff

source

Manifolds.base_group — Method

base_group(A::AbstractGroupAction)

The group that acts in AbstractGroupAction A.

source

Manifolds.center_of_orbit — Function

center_of_orbit(
    A::AbstractGroupAction,
    pts,
    p,
    mean_method::AbstractApproximationMethod = GradientDescentEstimation(),
)

Calculate an action element $a$ of action A that is the mean element of the orbit of p with respect to given set of points pts. The mean is calculated using the method mean_method.

The orbit of $p$ with respect to the action of a group $\mathcal{G}$ is the set

\[O = \{ τ_a p : a ∈ \mathcal{G} \}.\]

This function is useful for computing means on quotients of manifolds by a Lie group action.

source

Manifolds.direction — Method

direction(::AbstractGroupAction{AD}) -> AD

Get the direction of the action: either LeftAction or RightAction.

source

Manifolds.group_manifold — Method

group_manifold(A::AbstractGroupAction)

The manifold the action A acts upon.

source

Manifolds.inverse_apply! — Method

inverse_apply!(A::AbstractGroupAction, q, a, p)

Apply inverse of action a to the point p with the rule specified by A. The result is saved in q.

source

Manifolds.inverse_apply — Method

inverse_apply(A::AbstractGroupAction, a, p)

Apply inverse of action a to the point p. The action is specified by A.

source

Manifolds.inverse_apply_diff — Method

inverse_apply_diff(A::AbstractGroupAction, a, p, X)

For group point $p ∈ \mathcal M$ and tangent vector $X ∈ T_p \mathcal M$, compute the action on $X$ of the differential of the inverse action of $a ∈ \mathcal{G}$, specified by rule A. Written as $(\mathrm{d}τ_a^{-1})_p$, with the specified left or right convention, the differential transports vectors.

\[(\mathrm{d}τ_a^{-1})_p : T_p \mathcal M → T_{τ_a^{-1} p} \mathcal M\]

source

Manifolds.optimal_alignment! — Method

optimal_alignment!(A::AbstractGroupAction, x, p, q)

Calculate an action element of action A that acts upon p to produce the element closest to q. The result is written to x.

source

Manifolds.optimal_alignment — Method

optimal_alignment(A::AbstractGroupAction, p, q)

Calculate an action element $a$ of action A that acts upon p to produce the element closest to q in the metric of the G-manifold:

\[\arg\min_{a ∈ \mathcal{G}} d_{\mathcal M}(τ_a p, q)\]

where $\mathcal{G}$ is the group that acts on the G-manifold $\mathcal M$.

source

Group operation action

Manifolds.GroupOperationAction — Type

GroupOperationAction{AD<:ActionDirection,AS<:GroupActionSide,G<:AbstractDecoratorManifold} <: AbstractGroupAction{AD}

Action of a group upon itself via left or right translation, either from left or right side. 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}$.

Constructor

GroupOperationAction(group::AbstractDecoratorManifold, AD::ActionDirectionAndSide = LeftForwardAction())

source

Manifolds.action_side — Method

action_side(A::GroupOperationAction)

Return whether GroupOperationAction A acts on the LeftSide or RightSide.

source

Manifolds.apply_diff_group — Method

apply_diff_group(A::GroupOperationAction, a, X, p)

Compute differential of GroupOperationAction A with respect to group element at tangent vector X:

\[(\mathrm{d}τ^p) : T_{a} \mathcal G → T_{τ_a p} \mathcal G\]

There are four cases:

left action from the left side: $L_a: p ↦ a \circ p$, where

\[(\mathrm{d}L_a) : T_{a} \mathcal G → T_{a \circ p} \mathcal G.\]

right action from the left side: $L'_a: p ↦ a^{-1} \circ p$, where

\[(\mathrm{d}L'_a) : T_{a} \mathcal G → T_{a^{-1} \circ p} \mathcal G.\]

right action from the right side: $R_a: p ↦ p \circ a$, where

\[(\mathrm{d}R_a) : T_{a} \mathcal G → T_{p \circ a} \mathcal G.\]

left action from the right side: $R'_a: p ↦ p \circ a^{-1}$, where

\[(\mathrm{d}R'_a) : T_{a} \mathcal G → T_{p \circ a^{-1}} \mathcal G.\]

source

Rotation action

Manifolds.ColumnwiseMultiplicationAction — Type

ColumnwiseMultiplicationAction{
    TAD<:ActionDirection,
    TM<:AbstractManifold,
    TO<:GeneralUnitaryMultiplicationGroup,
} <: AbstractGroupAction{TAD}

Action of the (special) unitary or orthogonal group GeneralUnitaryMultiplicationGroup of type On columns of points on a matrix manifold M.

Constructor

ColumnwiseMultiplicationAction(
    M::AbstractManifold,
    On::GeneralUnitaryMultiplicationGroup,
    AD::ActionDirection = LeftAction(),
)

source

Manifolds.RotationAction — Type

RotationAction(
    M::AbstractManifold,
    SOn::SpecialOrthogonal,
    AD::ActionDirection = LeftAction(),
)

Space of actions of the SpecialOrthogonal group $\mathrm{SO}(n)$ on a Euclidean-like manifold M of dimension n.

source

Manifolds.RotationAroundAxisAction — Type

RotationAroundAxisAction(axis::AbstractVector)

Space of actions of the circle group RealCircleGroup on $ℝ^3$ around given axis.

source

Manifolds.RowwiseMultiplicationAction — Type

RowwiseMultiplicationAction{
    TAD<:ActionDirection,
    TM<:AbstractManifold,
    TO<:GeneralUnitaryMultiplicationGroup,
} <: AbstractGroupAction{TAD}

Action of the (special) unitary or orthogonal group GeneralUnitaryMultiplicationGroup of type On columns of points on a matrix manifold M.

Constructor

RowwiseMultiplicationAction(
    M::AbstractManifold,
    On::GeneralUnitaryMultiplicationGroup,
    AD::ActionDirection = LeftAction(),
)

source

Manifolds.apply — Method

apply(A::RotationAroundAxisAction, θ, p)

Rotate point p from Euclidean(3) manifold around axis A.axis by angle θ. The formula reads

\[p_{rot} = (\cos(θ))p + (k×p) \sin(θ) + k (k⋅p) (1-\cos(θ)),\]

where $k$ is the vector A.axis and ⋅ is the dot product.

source

Manifolds.optimal_alignment — Method

optimal_alignment(A::LeftColumnwiseMultiplicationAction, p, q)

Compute optimal alignment for the left ColumnwiseMultiplicationAction, i.e. the group element $O^{*}$ that, when it acts on p, returns the point closest to q. Details of computation are described in Section 2.2.1 of [SK16].

The formula reads

\[O^{*} = \begin{cases} UV^T & \text{if } \operatorname{det}(p q^{\mathrm{T}}) \geq 0\\ U K V^{\mathrm{T}} & \text{otherwise} \end{cases}\]

where $U \Sigma V^{\mathrm{T}}$ is the SVD decomposition of $p q^{\mathrm{T}}$ and $K$ is the unit diagonal matrix with the last element on the diagonal replaced with -1.

source

Translation action

Manifolds.TranslationAction — Type

TranslationAction(
    M::AbstractManifold,
    Rn::TranslationGroup,
    AD::ActionDirection = LeftAction(),
)

Space of actions of the TranslationGroup $\mathrm{T}(n)$ on a Euclidean-like manifold M.

The left and right actions are equivalent.

source

Rotation-translation action (special Euclidean)

Manifolds.ColumnwiseSpecialEuclideanAction — Type

ColumnwiseSpecialEuclideanAction{
    TM<:AbstractManifold,
    TSE<:SpecialEuclidean,
    TAD<:ActionDirection,
} <: AbstractGroupAction{TAD}

Action of the special Euclidean group SpecialEuclidean of type SE columns of points on a matrix manifold M.

Constructor

ColumnwiseSpecialEuclideanAction(
    M::AbstractManifold,
    SE::SpecialEuclidean,
    AD::ActionDirection = LeftAction(),
)

source

Manifolds.RotationTranslationAction — Type

RotationTranslationAction(
    M::AbstractManifold,
    SOn::SpecialEuclidean,
    AD::ActionDirection = LeftAction(),
)

Space of actions of the SpecialEuclidean group $\mathrm{SE}(n)$ on a Euclidean-like manifold M of dimension n.

Left actions corresponds to active transformations while right actions can be identified with passive transformations for a particular choice of a basis.

source

Manifolds.RotationTranslationActionOnVector — Type

RotationTranslationActionOnVector{TAD,𝔽,TE,TSE}

Alias for RotationTranslationAction where the manifold M is Euclidean or TranslationGroup with size of type TE, and SpecialEuclidean group has size type TSE.

source

Manifolds.apply — Method

apply(::RotationTranslationActionOnVector{LeftAction}, a::ArrayPartition, p)

Rotate point p by a.x[2] and translate it by a.x[1].

source

Manifolds.apply — Method

apply(::RotationTranslationActionOnVector{RightAction}, a::ArrayPartition, p)

Translate point p by -a.x[1] and rotate it by inverse of a.x[2].

source

Manifolds.apply_diff — Method

apply_diff(
    ::RotationTranslationActionOnVector{LeftAction},
    a::ArrayPartition,
    p,
    X,
)

Compute differential of apply on left RotationTranslationActionOnVector, with respect to p, i.e. left-multiply vector X tangent at p by a.x[2].

source

Manifolds.apply_diff — Method

apply_diff(
    ::RotationTranslationActionOnVector{RightAction},
    a::ArrayPartition,
    p,
    X,
)

Compute differential of apply on right RotationTranslationActionOnVector, with respect to p, i.e. left-divide vector X tangent at p by a.x[2].

source

Manifolds.apply_diff_group — Method

apply_diff_group(
    ::RotationTranslationActionOnVector{LeftAction},
    ::SpecialEuclideanIdentity,
    X,
    p,
)

Compute differential of apply on left RotationTranslationActionOnVector, with respect to a at identity, i.e. left-multiply point p by X.x[2].

source

Manifolds.inverse_apply — Method

inverse_apply(::RotationTranslationActionOnVector{LeftAction}, a::ArrayPartition, p)

Translate point p by -a.x[1] and rotate it by inverse of a.x[2].

source

Manifolds.inverse_apply — Method

inverse_apply(::RotationTranslationActionOnVector{RightAction}, a::ArrayPartition, p)

Rotate point p by a.x[2] and translate it by a.x[1].

source

Manifolds.optimal_alignment — Method

optimal_alignment(A::LeftColumnwiseSpecialEuclideanAction, p, q)

Compute optimal alignment of p to q under the forward left ColumnwiseSpecialEuclideanAction. The algorithm, in sequence, computes optimal translation and optimal rotation.

source