Group actions

AbstractGroupAction{AD<:ActionDirection}

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

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\]

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.

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}}\]

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\]

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

base_group(A::AbstractGroupAction)

The group that acts in AbstractGroupAction A.

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.

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

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

group_manifold(A::AbstractGroupAction)

The manifold the action A acts upon.

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.

inverse_apply(A::AbstractGroupAction, a, p)

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

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\]

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.

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$.

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())

action_side(A::GroupOperationAction)

Return whether GroupOperationAction A acts on the LeftSide or RightSide.

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.\]

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

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

Constructor

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

ComplexPlanarRotation()

Action of the circle group CircleGroup on $ℝ^2$ by left multiplication.

QuaternionRotation

Action of the unit quaternion group Unitary(1, ℍ) on $ℝ^3$.

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.

RotationAroundAxisAction(axis::AbstractVector)

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

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(),
)

apply(A::ComplexPlanarRotation, g::Complex, p)

Rotate point p from Euclidean(2) manifold by the group element g. The formula reads

\[p_{rot} = \begin{bmatrix} \cos(θ) & \sin(θ)\\ -\sin(θ) & \cos(θ) \end{bmatrix} p,\]

where θ is the argument of complex number g.

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.

apply(A::QuaternionRotation, g::Quaternion, p)

Rotate point p from Euclidean(3) manifold through conjugation by the group element g. The formula reads

\[(0, p_{rot,x}, p_{rot,y}, p_{rot,z}) = g ⋅ (0, p_x, p_y, p_z) ⋅ g^{\mathrm{H}}\]

where $(0, p_x, p_y, p_z)$ is quaternion with non-real coefficients from encoding the point p and $g^{\mathrm{H}}$ is quaternion conjugate of $g$.

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.

quaternion_rotation_matrix(g::Quaternions.Quaternion)

Compute rotation matrix for RotationAction corresponding to QuaternionRotation by g.

See https://www.songho.ca/opengl/gl_quaternion.html for details.

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.

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(),
)

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.

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.

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].