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 theLeftSide
orRightSide
(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 ofapply
with respect to the object it acts upon.direction
: tells whether a given action isLeftAction
,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 callsapply
but it may be have a faster implementation for some actions.inverse_apply_diff
: counterpart ofapply_diff
forinverse_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 theLeftSide
or (RightAction
) on theRightSide
translation, or actions by inverses of elements (RightAction
on theLeftSide
andLeftAction
on theRightSide
). This is by default performed by callingcompose
with appropriate order of arguments. This function is separated fromcompose
mostly to easily represent its differential,translate_diff
.translate_diff
: differential oftranslate
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 ofSpecialOrthogonal
group on different manifolds.TranslationAction
, which is the action ofTranslationGroup
group on different manifolds.
Manifolds.AbstractGroupAction
โ TypeAbstractGroupAction{AD<:ActionDirection}
An abstract group action on a manifold. ActionDirection
AD
indicates whether it is a left or right action.
Manifolds.adjoint_apply_diff_group
โ Methodadjoint_apply_diff_group(A::AbstractGroupAction, a, X, p)
Pullback with respect to group element of group action A
.
Manifolds.apply!
โ Methodapply!(A::AbstractGroupAction, q, a, p)
Apply action a
to the point p
with the rule specified by A
. The result is saved in q
.
Manifolds.apply
โ Methodapply(A::AbstractGroupAction, a, p)
Apply action a
to the point p
using map , specified by A
. Unless otherwise specified, the right action is defined in terms of the left action:
Manifolds.apply_diff
โ Methodapply_diff(A::AbstractGroupAction, a, p, X)
For point and tangent vector , compute the action on of the differential of the action of , specified by rule A
. Written as , with the specified left or right convention, the differential transports vectors
Manifolds.apply_diff_group
โ Methodapply_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 be the group acting on manifold by the action A
. The action is of element on a point . The differential transforms vector X
from the tangent space at a โ \mathcal G
, into a tangent space of the manifold . When action on element p
is written as , with the specified left or right convention, the differential transforms vectors
See also
Manifolds.base_group
โ Methodbase_group(A::AbstractGroupAction)
The group that acts in AbstractGroupAction
A
.
Manifolds.center_of_orbit
โ Functioncenter_of_orbit(
A::AbstractGroupAction,
pts,
p,
mean_method::AbstractApproximationMethod = GradientDescentEstimation(),
)
Calculate an action element 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 with respect to the action of a group is the set
This function is useful for computing means on quotients of manifolds by a Lie group action.
Manifolds.direction
โ Methoddirection(::AbstractGroupAction{AD}) -> AD
Get the direction of the action: either LeftAction
or RightAction
.
Manifolds.group_manifold
โ Methodgroup_manifold(A::AbstractGroupAction)
The manifold the action A
acts upon.
Manifolds.inverse_apply!
โ Methodinverse_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
.
Manifolds.inverse_apply
โ Methodinverse_apply(A::AbstractGroupAction, a, p)
Apply inverse of action a
to the point p
. The action is specified by A
.
Manifolds.inverse_apply_diff
โ Methodinverse_apply_diff(A::AbstractGroupAction, a, p, X)
For group point and tangent vector , compute the action on of the differential of the inverse action of , specified by rule A
. Written as , with the specified left or right convention, the differential transports vectors.
Manifolds.optimal_alignment!
โ Methodoptimal_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
.
Manifolds.optimal_alignment
โ Methodoptimal_alignment(A::AbstractGroupAction, p, q)
Calculate an action element of action A
that acts upon p
to produce the element closest to q
in the metric of the G-manifold:
where is the group that acts on the G-manifold .
Group operation action
Manifolds.GroupOperationAction
โ TypeGroupOperationAction{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: ,
- right action from the left side: ,
- right action from the right side: ,
- left action from the right side: .
Constructor
GroupOperationAction(group::AbstractDecoratorManifold, AD::ActionDirectionAndSide = LeftForwardAction())
Manifolds.action_side
โ Methodaction_side(A::GroupOperationAction)
Return whether GroupOperationAction
A
acts on the LeftSide
or RightSide
.
Manifolds.apply_diff_group
โ Methodapply_diff_group(A::GroupOperationAction, a, X, p)
Compute differential of GroupOperationAction
A
with respect to group element at tangent vector X
:
There are four cases:
- left action from the left side: , where
- right action from the left side: , where
- right action from the right side: , where
- left action from the right side: , where
Rotation action
Manifolds.ColumnwiseMultiplicationAction
โ TypeColumnwiseMultiplicationAction{
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(),
)
Manifolds.ComplexPlanarRotation
โ TypeComplexPlanarRotation()
Action of the circle group CircleGroup
on by left multiplication.
Manifolds.QuaternionRotation
โ TypeQuaternionRotation
Action of the unit quaternion group Unitary
(1, โ)
on .
Manifolds.RotationAction
โ TypeRotationAction(
M::AbstractManifold,
SOn::SpecialOrthogonal,
AD::ActionDirection = LeftAction(),
)
Space of actions of the SpecialOrthogonal
group on a Euclidean-like manifold M
of dimension n
.
Manifolds.RotationAroundAxisAction
โ TypeRotationAroundAxisAction(axis::AbstractVector)
Space of actions of the circle group RealCircleGroup
on around given axis
.
Manifolds.RowwiseMultiplicationAction
โ TypeRowwiseMultiplicationAction{
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(),
)
Manifolds.apply
โ Methodapply(A::ComplexPlanarRotation, g::Complex, p)
Rotate point p
from Euclidean(2)
manifold by the group element g
. The formula reads
where ฮธ
is the argument of complex number g
.
Manifolds.apply
โ Methodapply(A::RotationAroundAxisAction, ฮธ, p)
Rotate point p
from Euclidean(3)
manifold around axis A.axis
by angle ฮธ
. The formula reads
where is the vector A.axis
and โ
is the dot product.
Manifolds.apply
โ Methodapply(A::QuaternionRotation, g::Quaternion, p)
Rotate point p
from Euclidean
(3)
manifold through conjugation by the group element g
. The formula reads
where is quaternion with non-real coefficients from encoding the point p
and is quaternion conjugate of .
Manifolds.optimal_alignment
โ Methodoptimal_alignment(A::LeftColumnwiseMultiplicationAction, p, q)
Compute optimal alignment for the left ColumnwiseMultiplicationAction
, i.e. the group element 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
where is the SVD decomposition of and is the unit diagonal matrix with the last element on the diagonal replaced with -1.
Manifolds.quaternion_rotation_matrix
โ Methodquaternion_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.
Translation action
Manifolds.TranslationAction
โ TypeTranslationAction(
M::AbstractManifold,
Rn::TranslationGroup,
AD::ActionDirection = LeftAction(),
)
Space of actions of the TranslationGroup
on a Euclidean-like manifold M
.
The left and right actions are equivalent.
Rotation-translation action (special Euclidean)
Manifolds.ColumnwiseSpecialEuclideanAction
โ TypeColumnwiseSpecialEuclideanAction{
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(),
)
Manifolds.RotationTranslationAction
โ TypeRotationTranslationAction(
M::AbstractManifold,
SOn::SpecialEuclidean,
AD::ActionDirection = LeftAction(),
)
Space of actions of the SpecialEuclidean
group 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.
Manifolds.RotationTranslationActionOnVector
โ TypeRotationTranslationActionOnVector{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
.
Manifolds.apply_diff_group
โ Methodapply_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]
.