Group manifolds

AbstractGroupOperation

Abstract type for smooth binary operations $∘$ on elements of a Lie group $\mathcal{G}$:

\[∘ : \mathcal{G} × \mathcal{G} → \mathcal{G}\]

An operation can be either defined for a specific group manifold over number system 𝔽 or in general, by defining for an operation Op the following methods:

identity_element!(::AbstractDecoratorManifold, q, q)
inv!(::AbstractDecoratorManifold, q, p)
_compose!(::AbstractDecoratorManifold, x, p, q)

Note that a manifold is connected with an operation by wrapping it with a decorator, AbstractDecoratorManifold using the IsGroupManifold to specify the operation. For a concrete case the concrete wrapper GroupManifold can be used.

AbstractInvarianceTrait <: AbstractTrait

A common supertype for anz AbstractTrait related to metric invariance

ActionDirection

Direction of action on a manifold, either LeftAction or RightAction.

GroupActionSide

Side of action on a manifold, either LeftSide or RightSide.

GroupExponentialRetraction{D<:ActionDirectionAndSide} <: AbstractRetractionMethod

Retraction using the group exponential exp_lie "translated" to any point on the manifold.

For more details, see retract.

Constructor

GroupExponentialRetraction(conv::ActionDirectionAndSide = LeftAction())

GroupLogarithmicInverseRetraction{D<:ActionDirectionAndSide} <: AbstractInverseRetractionMethod

Retraction using the group logarithm log_lie "translated" to any point on the manifold.

For more details, see inverse_retract.

Constructor

GroupLogarithmicInverseRetraction(conv::ActionDirectionAndSide = LeftForwardAction())

HasBiinvariantMetric <: AbstractInvarianceTrait

Specify that the default metric functions for the bi-invariant metric on a GroupManifold are to be used.

HasLeftInvariantMetric <: AbstractInvarianceTrait

Specify that the default metric functions for the left-invariant metric on a GroupManifold are to be used.

HasRightInvariantMetric <: AbstractInvarianceTrait

Specify that the default metric functions for the right-invariant metric on a GroupManifold are to be used.

Identity{O<:AbstractGroupOperation}

Represent the group identity element $e ∈ \mathcal{G}$ on a Lie group $\mathcal G$ with AbstractGroupOperation of type O.

Similar to the philosophy that points are agnostic of their group at hand, the identity does not store the group g it belongs to. However it depends on the type of the AbstractGroupOperation used.

See also identity_element on how to obtain the corresponding AbstractManifoldPoint or array representation.

Constructors

Identity(G::AbstractDecoratorManifold{𝔽})
Identity(o::O)
Identity(::Type{O})

create the identity of the corresponding subtype O<:AbstractGroupOperation

IsGroupManifold{O<:AbstractGroupOperation} <: AbstractTrait

A trait to declare an AbstractManifold as a manifold with group structure with operation of type O.

Using this trait you can turn a manifold that you implement implictly into a Lie group. If you wish to decorate an existing manifold with one (or different) AbstractGroupActions, see GroupManifold.

Constructor

IsGroupManifold(op::AbstractGroupOperation)

LeftAction()

Left action of a group on a manifold. For a forward action $α: G×X → X$ it is characterized by

\[α(g, α(h, x)) = α(gh, x)\]

for all $g, h ∈ G$ and $x ∈ X$.

LeftSide()

An action of a group on a manifold that acts from the left side, i.e. $α: G×X → X$.

RightAction()

Right action of a group on a manifold. For a forward action $α: G×X → X$ it is characterized by

\[α(g, α(h, x)) = α(hg, x)\]

for all $g, h ∈ G$ and $x ∈ X$.

Note that a right action may act from either left or right side in an expression.

RightSide()

An action of a group on a manifold that acts from the right side, i.e. $α: X×G → X$.

inv(G::AbstractDecoratorManifold, p)

Inverse $p^{-1} ∈ \mathcal{G}$ of an element $p ∈ \mathcal{G}$, such that $p \circ p^{-1} = p^{-1} \circ p = e ∈ \mathcal{G}$, where $e$ is the Identity element of $\mathcal{G}$.

adjoint_action(G::AbstractDecoratorManifold, p, X)

Adjoint action of the element p of the Lie group G on the element X of the corresponding Lie algebra.

It is defined as the differential of the group authomorphism $Ψ_p(q) = pqp⁻¹$ at the identity of G.

The formula reads

\[\operatorname{Ad}_p(X) = dΨ_p(e)[X]\]

where $e$ is the identity element of G.

Note that the adjoint representation of a Lie group isn't generally faithful. Notably the adjoint representation of SO(2) is trivial.

adjoint_inv_diff(G::AbstractDecoratorManifold, p, X)

Compute the value of pullback of inverse $p^{-1} ∈ \mathcal{G}$ of an element $p ∈ \mathcal{G}$ at tangent vector X at $p^{-1}$. The result is a tangent vector at $p$.

compose(G::AbstractDecoratorManifold, p, q)

Compose elements $p,q ∈ \mathcal{G}$ using the group operation $p \circ q$.

For implementing composition on a new group manifold, please overload _compose instead so that methods with Identity arguments are not ambiguous.

exp_lie(G, X)
exp_lie!(G, q, X)

Compute the group exponential of the Lie algebra element X. It is equivalent to the exponential map defined by the CartanSchoutenMinus connection.

Given an element $X ∈ 𝔤 = T_e \mathcal{G}$, where $e$ is the Identity element of the group $\mathcal{G}$, and $𝔤$ is its Lie algebra, the group exponential is the map

\[\exp : 𝔤 → \mathcal{G},\]

such that for $t,s ∈ ℝ$, $γ(t) = \exp (t X)$ defines a one-parameter subgroup with the following properties. Note that one-parameter subgroups are commutative (see [Suh13], section 3.5), even if the Lie group itself is not commutative.

\[\begin{aligned} γ(t) &= γ(-t)^{-1}\\ γ(t + s) &= γ(t) \circ γ(s) = γ(s) \circ γ(t)\\ γ(0) &= e\\ \lim_{t → 0} \frac{d}{dt} γ(t) &= X. \end{aligned}\]

For example for the MultiplicationOperation and either Number or AbstractMatrix the Lie exponential is the numeric/matrix exponential.

\[\exp X = \operatorname{Exp} X = \sum_{n=0}^∞ \frac{1}{n!} X^n.\]

Since this function also depends on the group operation, make sure to implement the corresponding trait version exp_lie(::TraitList{<:IsGroupManifold}, G, X).

get_coordinates_lie(G::AbstractManifold, X, B::AbstractBasis)

Get the coordinates of an element X from the Lie algebra og G with respect to a basis B. This is similar to calling get_coordinates at the p=Identity(G).

get_vector_lie(G::AbstractDecoratorManifold, a, B::AbstractBasis)

Reconstruct a tangent vector from the Lie algebra of G from cooordinates a of a basis B. This is similar to calling get_vector at the p=Identity(G).

identity_element(G::AbstractDecoratorManifold, p)

Return a point representation of the Identity on the IsGroupManifoldG, where p indicates the type to represent the identity.

identity_element(G::AbstractDecoratorManifold)

Return a point representation of the Identity on the IsGroupManifoldG. By default this representation is the default array or number representation. It should return the corresponding default representation of $e$ as a point on G if points are not represented by arrays.

inv_diff(G::AbstractDecoratorManifold, p, X)

Compute the value of differential of inverse $p^{-1} ∈ \mathcal{G}$ of an element $p ∈ \mathcal{G}$ at tangent vector X at p. The result is a tangent vector at $p^{-1}$.

inverse_translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirectionAndSide=LeftForwardAction())

Inverse translate group element $q$ by $p$ with the translation $τ_p^{-1}$ with the specified convention, either left forward ($L_p^{-1}$), left backward ($R'_p^{-1}$), right backward ($R_p^{-1}$) or right forward ($L'_p^{-1}$), defined as ```math \begin{aligned} Lp^{-1} &: q ↦ p^{-1} \circ q\ L'p^{-1} &: q ↦ p \circ q\ Rp^{-1} &: q ↦ q \circ p^{-1}\ R'p^{-1} &: q ↦ q \circ p. \end{aligned}

inverse_translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirectionAndSide=LeftForwardAction())

For group elements $p, q ∈ \mathcal{G}$ and tangent vector $X ∈ T_q \mathcal{G}$, compute the action on $X$ of the differential of the inverse translation $τ_p$ by $p$, with the specified left or right convention. The differential transports vectors:

\[(\mathrm{d}τ_p^{-1})_q : T_q \mathcal{G} → T_{τ_p^{-1} q} \mathcal{G}\\\]

is_group_manifold(G::GroupManifold)
is_group_manifold(G::AbstractManifold, o::AbstractGroupOperation)

returns whether an AbstractDecoratorManifold is a group manifold with AbstractGroupOperationo. For a GroupManifoldG this checks whether the right operations is stored within G.

is_identity(G::AbstractDecoratorManifold, q; kwargs)

Check whether q is the identity on the IsGroupManifoldG, i.e. it is either the Identity{O} with the corresponding AbstractGroupOperationO, or (approximately) the correct point representation.

lie_bracket(G::AbstractDecoratorManifold, X, Y)

Lie bracket between elements X and Y of the Lie algebra corresponding to the Lie group G, cf. IsGroupManifold.

This can be used to compute the adjoint representation of a Lie algebra. Note that this representation isn't generally faithful. Notably the adjoint representation of 𝔰𝔬(2) is trivial.

log_lie(G, q)
log_lie!(G, X, q)

Compute the Lie group logarithm of the Lie group element q. It is equivalent to the logarithmic map defined by the CartanSchoutenMinus connection.

Given an element $q ∈ \mathcal{G}$, compute the right inverse of the group exponential map exp_lie, that is, the element $\log q = X ∈ 𝔤 = T_e \mathcal{G}$, such that $q = \exp X$

\[\log q = \operatorname{Log} q = \sum_{n=1}^∞ \frac{(-1)^{n+1}}{n} (q - e)^n,\]

where $e$ here is the Identity element, that is, $1$ for numeric $q$ or the identity matrix $I_m$ for matrix $q ∈ ℝ^{m×m}$.

Since this function also depends on the group operation, make sure to implement either

• _log_lie(G, q) and _log_lie!(G, X, q) for the points not being the Identity
• the trait version log_lie(::TraitList{<:IsGroupManifold}, G, e), log_lie(::TraitList{<:IsGroupManifold}, G, X, e) for own implementations of the identity case.

switch_direction(::ActionDirection)

Returns type of action between left and right. This function does not affect side of action, see switch_side.

switch_side(::GroupActionSide)

Returns side of action between left and right. This function does not affect the action being left or right, see switch_direction.

translate(G::AbstractDecoratorManifold, p, q, conv::ActionDirectionAndSide=LeftForwardAction()])

Translate group element $q$ by $p$ with the translation $τ_p$ with the specified convention, either left forward ($L_p$), left backward ($R'_p$), right backward ($R_p$) or right forward ($L'_p$), defined as

\[\begin{aligned} L_p &: q ↦ p \circ q\\ L'_p &: q ↦ p^{-1} \circ q\\ R_p &: q ↦ q \circ p\\ R'_p &: q ↦ q \circ p^{-1}. \end{aligned}\]

translate_diff(G::AbstractDecoratorManifold, p, q, X, conv::ActionDirectionAndSide=LeftForwardAction())

For group elements $p, q ∈ \mathcal{G}$ and tangent vector $X ∈ T_q \mathcal{G}$, compute the action of the differential of the translation $τ_p$ by $p$ on $X$, with the specified left or right convention. The differential transports vectors:

\[(\mathrm{d}τ_p)_q : T_q \mathcal{G} → T_{τ_p q} \mathcal{G}\\\]

hat(M::AbstractDecoratorManifold{𝔽,O}, ::Identity{O}, Xⁱ) where {𝔽,O<:AbstractGroupOperation}

Given a basis $e_i$ on the tangent space at a the Identity and tangent component vector $X^i$, compute the equivalent vector representation ``X=X^i e_i**, where Einstein summation notation is used:

\[∧ : X^i ↦ X^i e_i\]

For array manifolds, this converts a vector representation of the tangent vector to an array representation. The vee map is the hat map's inverse.

inverse_retract(
    G::AbstractDecoratorManifold,
    p,
    X,
    method::GroupLogarithmicInverseRetraction,
)

Compute the inverse retraction using the group logarithm log_lie "translated" to any point on the manifold. With a group translation (translate) $τ_p$ in a specified direction, the retraction is

\[\operatorname{retr}_p^{-1} = (\mathrm{d}τ_p)_e \circ \log \circ τ_p^{-1},\]

where $\log$ is the group logarithm (log_lie), and $(\mathrm{d}τ_p)_e$ is the action of the differential of translation $τ_p$ evaluated at the identity element $e$ (see translate_diff).

retract(
    G::AbstractDecoratorManifold,
    p,
    X,
    method::GroupExponentialRetraction,
)

Compute the retraction using the group exponential exp_lie "translated" to any point on the manifold. With a group translation (translate) $τ_p$ in a specified direction, the retraction is

\[\operatorname{retr}_p = τ_p \circ \exp \circ (\mathrm{d}τ_p^{-1})_p,\]

where $\exp$ is the group exponential (exp_lie), and $(\mathrm{d}τ_p^{-1})_p$ is the action of the differential of inverse translation $τ_p^{-1}$ evaluated at $p$ (see inverse_translate_diff).

vee(M::AbstractManifold, p, X)

Given a basis $e_i$ on the tangent space at a point p and tangent vector X, compute the vector components $X^i$, such that $X = X^i e_i$, where Einstein summation notation is used:

\[\vee : X^i e_i ↦ X^i\]

For array manifolds, this converts an array representation of the tangent vector to a vector representation. The hat map is the vee map's inverse.

GroupManifold{𝔽,M<:AbstractManifold{𝔽},O<:AbstractGroupOperation} <: AbstractDecoratorManifold{𝔽}

Concrete decorator for a smooth manifold that equips the manifold with a group operation, thus making it a Lie group. See IsGroupManifold for more details.

Group manifolds by default forward metric-related operations to the wrapped manifold.

Constructor

GroupManifold(manifold, op)

Define the group operation op acting on the manifold manifold, hence if op acts smoothly, this forms a Lie group.

rand(::GroupManifold; vector_at=nothing, σ=1.0)
rand!(::GroupManifold, pX; vector_at=nothing, kwargs...)
rand(::TraitList{IsGroupManifold}, M; vector_at=nothing, σ=1.0)
rand!(TraitList{IsGroupManifold}, M, pX; vector_at=nothing, kwargs...)

Compute a random point or tangent vector on a Lie group.

For points this just means to generate a random point on the underlying manifold itself.

For tangent vectors, an element in the Lie Algebra is generated.

AdditionOperation <: AbstractGroupOperation

Group operation that consists of simple addition.

adjoint_inv_diff(::AdditionGroupTrait, G::AbstractDecoratorManifold, p, X)

Compute the value of pullback of additive matrix inversion $p ↦ -p$ at $X$, i.e. $-X$.

inv_diff(::AdditionGroupTrait, G::AbstractDecoratorManifold, p, X)

Compute the value of differential of additive matrix inversion $p ↦ -p$ at $X$, i.e. $-X$.

MultiplicationOperation <: AbstractGroupOperation

Group operation that consists of multiplication.

adjoint_inv_diff(::MultiplicationGroupTrait, G::AbstractDecoratorManifold, p, X)

Compute the value of differential of matrix inversion $p ↦ p^{-1}$ at $X$. When tangent vectors are represented in Lie algebra in a left-invariant way, the formula reads $-p^\mathrm{T}X(p^{-1})^\mathrm{T}$. For matrix groups with ambient space tangent vectors, the formula would read $-(p^{-1})^\mathrm{T}X(p^{-1})^\mathrm{T}$. See the section about matrix inverse in [Gil08].

inv_diff(::MultiplicationGroupTrait, G::AbstractDecoratorManifold, p, X)

Compute the value of differential of matrix inversion $p ↦ p^{-1}$ at $X$. When tangent vectors are represented in Lie algebra in a left-invariant way, the formula reads $-pXp^{-1}$. For matrix groups with ambient space tangent vectors, the formula would read $-p^{-1}Xp^{-1}$. See the section about matrix inverse in [Gil08].

CircleGroup <: GroupManifold{Circle{ℂ},MultiplicationOperation}

The circle group is the complex circle (Circle(ℂ)) equipped with the group operation of complex multiplication (MultiplicationOperation).

RealCircleGroup <: GroupManifold{Circle{ℝ},AdditionOperation}

The real circle group is the real circle (Circle(ℝ)) equipped with the group operation of addition (AdditionOperation).

GeneralLinear{T,𝔽} <: AbstractDecoratorManifold{𝔽}

The general linear group, that is, the group of all invertible matrices in $𝔽^{n×n}$.

The default metric is the left-$\mathrm{GL}(n)$-right-$\mathrm{O}(n)$-invariant metric whose inner product is

\[⟨X_p,Y_p⟩_p = ⟨p^{-1}X_p,p^{-1}Y_p⟩_\mathrm{F} = ⟨X_e, Y_e⟩_\mathrm{F},\]

where $X_p, Y_p ∈ T_p \mathrm{GL}(n, 𝔽)$, $X_e = p^{-1}X_p ∈ 𝔤𝔩(n) = T_e \mathrm{GL}(n, 𝔽) = 𝔽^{n×n}$ is the corresponding vector in the Lie algebra, and $⟨⋅,⋅⟩_\mathrm{F}$ denotes the Frobenius inner product.

By default, tangent vectors $X_p$ are represented with their corresponding Lie algebra vectors $X_e = p^{-1}X_p$.

exp(G::GeneralLinear, p, X)

Compute the exponential map on the GeneralLinear group.

The exponential map is

\[\exp_p \colon X ↦ p \operatorname{Exp}(X^\mathrm{H}) \operatorname{Exp}(X - X^\mathrm{H}),\]

where $\operatorname{Exp}(⋅)$ denotes the matrix exponential, and $⋅^\mathrm{H}$ is the conjugate transpose [ALRV14] [NM16].

log(G::GeneralLinear, p, q)

Compute the logarithmic map on the GeneralLinear(n) group.

The algorithm proceeds in two stages. First, the point $r = p^{-1} q$ is projected to the nearest element (under the Frobenius norm) of the direct product subgroup $\mathrm{O}(n) × S^+$, whose logarithmic map is exactly computed using the matrix logarithm. This initial tangent vector is then refined using the NLSolveInverseRetraction.

For GeneralLinear(n, ℂ), the logarithmic map is instead computed on the realified supergroup GeneralLinear(2n) and the resulting tangent vector is then complexified.

Note that this implementation is experimental.

Random.rand(G::GeneralLinear; vector_at=nothing, kwargs...)

If vector_at is nothing, return a random point on the GeneralLinear group G by using rand in the embedding.

If vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the GeneralLinear by using by using rand in the embedding.

HeisenbergGroup{T} <: AbstractDecoratorManifold{ℝ}

Heisenberg group HeisenbergGroup(n) is the group of $(n+2)×(n+2)$ matrices [BP08]

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ \mathbf{0} & I_n & \mathbf{b} \\ 0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ unit matrix, $\mathbf{a}$ is a row vector of length $n$, $\mathbf{b}$ is a column vector of length $n$ and $c$ is a real number. The group operation is matrix multiplication.

The left-invariant metric on the manifold is used.

exp(M::HeisenbergGroup, p, X)

Exponential map on the HeisenbergGroupM with the left-invariant metric. The expression reads

\[\exp_{\begin{bmatrix} 1 & \mathbf{a}_p & c_p \\ \mathbf{0} & I_n & \mathbf{b}_p \\ 0 & \mathbf{0} & 1 \end{bmatrix}}\left(\begin{bmatrix} 0 & \mathbf{a}_X & c_X \\ \mathbf{0} & 0_n & \mathbf{b}_X \\ 0 & \mathbf{0} & 0 \end{bmatrix}\right) = \begin{bmatrix} 1 & \mathbf{a}_p + \mathbf{a}_X & c_p + c_X + \mathbf{a}_X⋅\mathbf{b}_X/2 + \mathbf{a}_p⋅\mathbf{b}_X \\ \mathbf{0} & I_n & \mathbf{b}_p + \mathbf{b}_X \\ 0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

log(G::HeisenbergGroup, p, q)

Compute the logarithmic map on the HeisenbergGroup group. The formula reads

\[\log_{\begin{bmatrix} 1 & \mathbf{a}_p & c_p \\ \mathbf{0} & I_n & \mathbf{b}_p \\ 0 & \mathbf{0} & 1 \end{bmatrix}}\left(\begin{bmatrix} 1 & \mathbf{a}_q & c_q \\ \mathbf{0} & I_n & \mathbf{b}_q \\ 0 & \mathbf{0} & 1 \end{bmatrix}\right) = \begin{bmatrix} 0 & \mathbf{a}_q - \mathbf{a}_p & c_q - c_p + \mathbf{a}_p⋅\mathbf{b}_p - \mathbf{a}_q⋅\mathbf{b}_q - (\mathbf{a}_q - \mathbf{a}_p)⋅(\mathbf{b}_q - \mathbf{b}_p) / 2 \\ \mathbf{0} & 0_n & \mathbf{b}_q - \mathbf{b}_p \\ 0 & \mathbf{0} & 0 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

Random.rand(M::HeisenbergGroup; vector_at = nothing, σ::Real=1.0)

If vector_at is nothing, return a random point on the HeisenbergGroupM by sampling elements of the first row and the last column from the normal distribution with mean 0 and standard deviation σ.

If vector_at is not nothing, return a random tangent vector from the tangent space of the point vector_at on the HeisenbergGroup by using a normal distribution with mean 0 and standard deviation σ.

exp_lie(M::HeisenbergGroup, X)

Lie group exponential for the HeisenbergGroupM of the vector X. The formula reads

\[\exp\left(\begin{bmatrix} 0 & \mathbf{a} & c \\ \mathbf{0} & 0_n & \mathbf{b} \\ 0 & \mathbf{0} & 0 \end{bmatrix}\right) = \begin{bmatrix} 1 & \mathbf{a} & c + \mathbf{a}⋅\mathbf{b}/2 \\ \mathbf{0} & I_n & \mathbf{b} \\ 0 & \mathbf{0} & 1 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

log_lie(M::HeisenbergGroup, p)

Lie group logarithm for the HeisenbergGroupM of the point p. The formula reads

\[\log\left(\begin{bmatrix} 1 & \mathbf{a} & c \\ \mathbf{0} & I_n & \mathbf{b} \\ 0 & \mathbf{0} & 1 \end{bmatrix}\right) = \begin{bmatrix} 0 & \mathbf{a} & c - \mathbf{a}⋅\mathbf{b}/2 \\ \mathbf{0} & 0_n & \mathbf{b} \\ 0 & \mathbf{0} & 0 \end{bmatrix}\]

where $I_n$ is the $n×n$ identity matrix, $0_n$ is the $n×n$ zero matrix and $\mathbf{a}⋅\mathbf{b}$ is dot product of vectors.

get_coordinates(M::HeisenbergGroup, p, X, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})

Get coordinates of tangent vector X at point p from the HeisenbergGroupM. Given a matrix

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ \mathbf{0} & I_n & \mathbf{b} \\ 0 & \mathbf{0} & 1 \end{bmatrix}\]

the coordinates are concatenated vectors $\mathbf{a}$, $\mathbf{b}$, and number $c$.

get_vector(M::HeisenbergGroup, p, Xⁱ, ::DefaultOrthonormalBasis{ℝ,TangentSpaceType})

Get tangent vector with coordinates Xⁱ at point p from the HeisenbergGroupM. Given a vector of coordinates $\begin{bmatrix}\mathbb{a} & \mathbb{b} & c\end{bmatrix}$ the tangent vector is equal to

\[\begin{bmatrix} 1 & \mathbf{a} & c \\ \mathbf{0} & I_n & \mathbf{b} \\ 0 & \mathbf{0} & 1 \end{bmatrix}\]

injectivity_radius(M::HeisenbergGroup)

Return the injectivity radius on the HeisenbergGroupM, which is $∞$.

project(M::HeisenbergGroup, p, X)

Project a matrix X in the Euclidean embedding onto the Lie algebra of HeisenbergGroupM. Sets the diagonal elements to 0 and all non-diagonal elements except the first row and the last column to 0.

project(M::HeisenbergGroup, p)

Project a matrix p in the Euclidean embedding onto the HeisenbergGroupM. Sets the diagonal elements to 1 and all non-diagonal elements except the first row and the last column to 0.

GeneralUnitaryMultiplicationGroup{T,𝔽,S} <: AbstractDecoratorManifold{𝔽}

A generic type for Lie groups based on a unitary property and matrix multiplcation, see e.g. Orthogonal, SpecialOrthogonal, Unitary, and SpecialUnitary

 exp_lie(G::Orthogonal{TypeParameter{Tuple{2}}}, X)
 exp_lie(G::SpecialOrthogonal{TypeParameter{Tuple{2}}}, X)

Compute the Lie group exponential map on the Orthogonal(2) or SpecialOrthogonal(2) group. Given $X = \begin{pmatrix} 0 & -θ \\ θ & 0 \end{pmatrix}$, the group exponential is

\[\exp_e \colon X ↦ \begin{pmatrix} \cos θ & -\sin θ \\ \sin θ & \cos θ \end{pmatrix}.\]

 exp_lie(G::Orthogonal{TypeParameter{Tuple{4}}}, X)
 exp_lie(G::SpecialOrthogonal{TypeParameter{Tuple{4}}}, X)

Compute the group exponential map on the Orthogonal(4) or the SpecialOrthogonal group. The algorithm used is a more numerically stable form of those proposed in [GX02], [AR13].

Orthogonal{T} = GeneralUnitaryMultiplicationGroup{T,ℝ,AbsoluteDeterminantOneMatrices}

Orthogonal group $\mathrm{O}(n)$ represented by OrthogonalMatrices.

Constructor

Orthogonal(n::Int; parameter::Symbol=:type)

SpecialOrthogonal{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,DeterminantOneMatrices}

Special orthogonal group $\mathrm{SO}(n)$ represented by rotation matrices, see Rotations.

Constructor

SpecialOrthogonal(n)

SpecialUnitary{n} = GeneralUnitaryMultiplicationGroup{n,ℝ,GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices}}

The special unitary group $\mathrm{SU}(n)$ represented by unitary matrices of determinant +1.

The tangent spaces are of the form

\[T_p\mathrm{SU}(x) = \bigl\{ X \in \mathbb C^{n×n} \big| X = pY \text{ where } Y = -Y^{\mathrm{H}} \bigr\}\]

and we represent tangent vectors by just storing the SkewHermitianMatrices$Y$, or in other words we represent the tangent spaces employing the Lie algebra $\mathfrak{su}(n)$.

Constructor

SpecialUnitary(n)

Generate the Lie group of $n×n$ unitary matrices with determinant +1.

project(G::SpecialUnitary, p)

Project p to the nearest point on the SpecialUnitary group G.

Given the singular value decomposition $p = U S V^\mathrm{H}$, with the singular values sorted in descending order, the projection is

\[\operatorname{proj}_{\mathrm{SU}(n)}(p) = U\operatorname{diag}\left[1,1,…,\det(U V^\mathrm{H})\right] V^\mathrm{H}.\]

The diagonal matrix ensures that the determinant of the result is $+1$.

 Unitary{n,𝔽} = GeneralUnitaryMultiplicationGroup{n,𝔽,AbsoluteDeterminantOneMatrices}

The group of unitary matrices $\mathrm{U}(n, 𝔽)$, either complex (when 𝔽=ℂ) or quaternionic (when 𝔽=ℍ)

The group consists of all points $p ∈ 𝔽^{n×n}$ where $p^{\mathrm{H}}p = pp^{\mathrm{H}} = I$.

The tangent spaces are if the form

\[T_p\mathrm{U}(n) = \bigl\{ X \in 𝔽^{n×n} \big| X = pY \text{ where } Y = -Y^{\mathrm{H}} \bigr\}\]

and we represent tangent vectors by just storing the SkewHermitianMatrices$Y$, or in other words we represent the tangent spaces employing the Lie algebra $\mathfrak{u}(n, 𝔽)$.

Quaternionic unitary group is isomorphic to the compact symplectic group of the same dimension.

Constructor

Unitary(n, 𝔽::AbstractNumbers=ℂ)

Construct $\mathrm{U}(n, 𝔽)$. See also Orthogonal(n) for the real-valued case.

exp_lie(G::Unitary{TypeParameter{Tuple{2}},ℂ}, X)

Compute the group exponential map on the Unitary(2) group, which is

\[\exp_e \colon X ↦ e^{\operatorname{tr}(X) / 2} \left(\cos θ I + \frac{\sin θ}{θ} \left(X - \frac{\operatorname{tr}(X)}{2} I\right)\right),\]

where $θ = \frac{1}{2} \sqrt{4\det(X) - \operatorname{tr}(X)^2}$.

PowerGroup{𝔽,T} <: GroupManifold{𝔽,<:AbstractPowerManifold{𝔽,M,RPT},ProductOperation}

Decorate a power manifold with a ProductOperation.

Constituent manifold of the power manifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.

Constructor

PowerGroup(manifold::AbstractPowerManifold)

PowerGroupNested

Alias to PowerGroup with NestedPowerRepresentation representation.

PowerGroupNestedReplacing

Alias to PowerGroup with NestedReplacingPowerRepresentation representation.

ProductGroup{𝔽,T} <: GroupManifold{𝔽,ProductManifold{T},ProductOperation}

Decorate a product manifold with a ProductOperation.

Each submanifold must also have a IsGroupManifold or a decorated instance of one. This type is mostly useful for equipping the direct product of group manifolds with an Identity element.

Constructor

ProductGroup(manifold::ProductManifold)

ProductOperation <: AbstractGroupOperation

Direct product group operation.

SemidirectProductGroup(N::GroupManifold, H::GroupManifold, A::AbstractGroupAction)

A group that is the semidirect product of a normal group $\mathcal{N}$ and a subgroup $\mathcal{H}$, written $\mathcal{G} = \mathcal{N} ⋊_θ \mathcal{H}$, where $θ: \mathcal{H} × \mathcal{N} → \mathcal{N}$ is an automorphism action of $\mathcal{H}$ on $\mathcal{N}$. The group $\mathcal{G}$ has the composition rule

\[g \circ g' = (n, h) \circ (n', h') = (n \circ θ_h(n'), h \circ h')\]

and the inverse

\[g^{-1} = (n, h)^{-1} = (θ_{h^{-1}}(n^{-1}), h^{-1}).\]

SemidirectProductOperation(action::AbstractGroupAction)

Group operation of a semidirect product group. The operation consists of the operation opN on a normal subgroup N, the operation opH on a subgroup H, and an automorphism action of elements of H on N. Only the action is stored.

identity_element(G::SemidirectProductGroup)

Get the identity element of SemidirectProductGroupG. Uses ArrayPartition from RecursiveArrayTools.jl to represent the point.

translate_diff(G::SemidirectProductGroup, p, q, X, conX::LeftForwardAction)

Perform differential of the left translation on the semidirect product group G.

Since the left translation is defined as (cf. SemidirectProductGroup):

\[L_{(n', h')} (n, h) = ( L_{n'} θ_{h'}(n), L_{h'} h)\]

then its differential can be computed as

\[\mathrm{d}L_{(n', h')}(X_n, X_h) = ( \mathrm{d}L_{n'} (\mathrm{d}θ_{h'}(X_n)), \mathrm{d}L_{h'} X_h).\]

SpecialEuclidean(n)

Special Euclidean group $\mathrm{SE}(n)$, the group of rigid motions.

$\mathrm{SE}(n)$ is the semidirect product of the TranslationGroup on $ℝ^n$ and SpecialOrthogonal(n)

\[\mathrm{SE}(n) ≐ \mathrm{T}(n) ⋊_θ \mathrm{SO}(n),\]

where $θ$ is the canonical action of $\mathrm{SO}(n)$ on $\mathrm{T}(n)$ by vector rotation.

This constructor is equivalent to calling

Tn = TranslationGroup(n)
SOn = SpecialOrthogonal(n)
SemidirectProductGroup(Tn, SOn, RotationAction(Tn, SOn))

Points on $\mathrm{SE}(n)$ may be represented as points on the underlying product manifold $\mathrm{T}(n) × \mathrm{SO}(n)$. For group-specific functions, they may also be represented as affine matrices with size (n + 1, n + 1) (see affine_matrix), for which the group operation is MultiplicationOperation.

SpecialEuclideanInGeneralLinear

An explicit isometric and homomorphic embedding of $\mathrm{SE}(n)$ in $\mathrm{GL}(n+1)$ and $𝔰𝔢(n)$ in $𝔤𝔩(n+1)$. Note that this is not a transparently isometric embedding.

Constructor

SpecialEuclideanInGeneralLinear(n)

_get_parameter(M::AbstractManifold)

Similar to get_parameter but it can be specialized for manifolds without breaking manifolds being parametrized by other manifolds.

adjoint_action(::SpecialEuclidean{TypeParameter{Tuple{3}}}, p, fX::TFVector{<:Any,VeeOrthogonalBasis{ℝ}})

Adjoint action of the SpecialEuclidean group on the vector with coefficients fX tangent at point p.

The formula for the coefficients reads $t×(R⋅ω) + R⋅r$ for the translation part and $R⋅ω$ for the rotation part, where t is the translation part of p, R is the rotation matrix part of p, r is the translation part of fX and ω is the rotation part of fX, $×$ is the cross product and $⋅$ is the matrix product.

affine_matrix(G::SpecialEuclidean, p) -> AbstractMatrix

Represent the point $p ∈ \mathrm{SE}(n)$ as an affine matrix. For $p = (t, R) ∈ \mathrm{SE}(n)$, where $t ∈ \mathrm{T}(n), R ∈ \mathrm{SO}(n)$, the affine representation is the $n + 1 × n + 1$ matrix

\[\begin{pmatrix} R & t \\ 0^\mathrm{T} & 1 \end{pmatrix}.\]

This function embeds $\mathrm{SE}(n)$ in the general linear group $\mathrm{GL}(n+1)$. It is an isometric embedding and group homomorphism [Ric88].

See also screw_matrix for matrix representations of the Lie algebra.

exp_lie(G::SpecialEuclidean{TypeParameter{Tuple{2}}}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(2)$, where $b ∈ 𝔱(2)$ and $Ω ∈ 𝔰𝔬(2)$:

\[\exp X = (t, R) = (U(θ) b, \exp Ω),\]

where $t ∈ \mathrm{T}(2)$, $R = \exp Ω$ is the group exponential on $\mathrm{SO}(2)$,

\[U(θ) = \frac{\sin θ}{θ} I_2 + \frac{1 - \cos θ}{θ^2} Ω,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

exp_lie(G::SpecialEuclidean{TypeParameter{Tuple{3}}}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(3)$, where $b ∈ 𝔱(3)$ and $Ω ∈ 𝔰𝔬(3)$:

\[\exp X = (t, R) = (U(θ) b, \exp Ω),\]

where $t ∈ \mathrm{T}(3)$, $R = \exp Ω$ is the group exponential on $\mathrm{SO}(3)$,

\[U(θ) = I_3 + \frac{1 - \cos θ}{θ^2} Ω + \frac{θ - \sin θ}{θ^3} Ω^2,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

exp_lie(G::SpecialEuclidean{n}, X)

Compute the group exponential of $X = (b, Ω) ∈ 𝔰𝔢(n)$, where $b ∈ 𝔱(n)$ and $Ω ∈ 𝔰𝔬(n)$:

\[\exp X = (t, R),\]

where $t ∈ \mathrm{T}(n)$ and $R = \exp Ω$ is the group exponential on $\mathrm{SO}(n)$.

In the screw_matrix representation, the group exponential is the matrix exponential (see exp_lie).

lie_bracket(G::SpecialEuclidean, X::ArrayPartition, Y::ArrayPartition)
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) the formula is $[X, Y] = XY-YX$, while in the ArrayPartition 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)$.

log_lie(G::SpecialEuclidean{TypeParameter{Tuple{2}}}, p)

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(2)$, where $t ∈ \mathrm{T}(2)$ and $R ∈ \mathrm{SO}(2)$:

\[\log p = (b, Ω) = (U(θ)^{-1} t, \log R),\]

where $b ∈ 𝔱(2)$, $Ω = \log R ∈ 𝔰𝔬(2)$ is the group logarithm on $\mathrm{SO}(2)$,

\[U(θ) = \frac{\sin θ}{θ} I_2 + \frac{1 - \cos θ}{θ^2} Ω,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

log_lie(G::SpecialEuclidean{TypeParameter{Tuple{3}}}, p)

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(3)$, where $t ∈ \mathrm{T}(3)$ and $R ∈ \mathrm{SO}(3)$:

\[\log p = (b, Ω) = (U(θ)^{-1} t, \log R),\]

where $b ∈ 𝔱(3)$, $Ω = \log R ∈ 𝔰𝔬(3)$ is the group logarithm on $\mathrm{SO}(3)$,

\[U(θ) = I_3 + \frac{1 - \cos θ}{θ^2} Ω + \frac{θ - \sin θ}{θ^3} Ω^2,\]

and $θ = \frac{1}{\sqrt{2}} \lVert Ω \rVert_e$ (see norm) is the angle of the rotation.

log_lie(G::SpecialEuclidean, p)

Compute the group logarithm of $p = (t, R) ∈ \mathrm{SE}(n)$, where $t ∈ \mathrm{T}(n)$ and $R ∈ \mathrm{SO}(n)$:

\[\log p = (b, Ω),\]

where $b ∈ 𝔱(n)$ and $Ω = \log R ∈ 𝔰𝔬(n)$ is the group logarithm on $\mathrm{SO}(n)$.

In the affine_matrix representation, the group logarithm is the matrix logarithm (see log_lie):

screw_matrix(G::SpecialEuclidean, X) -> AbstractMatrix

Represent the Lie algebra element $X ∈ 𝔰𝔢(n) = T_e \mathrm{SE}(n)$ as a screw matrix. For $X = (b, Ω) ∈ 𝔰𝔢(n)$, where $Ω ∈ 𝔰𝔬(n) = T_e \mathrm{SO}(n)$, the screw representation is the $n + 1 × n + 1$ matrix

\[\begin{pmatrix} Ω & b \\ 0^\mathrm{T} & 0 \end{pmatrix}.\]

This function embeds $𝔰𝔢(n)$ in the general linear Lie algebra $𝔤𝔩(n+1)$ but it's not a homomorphic embedding (see SpecialEuclideanInGeneralLinear for a homomorphic one).

See also affine_matrix for matrix representations of the Lie group.

translate_diff(G::SpecialEuclidean, p, q, X, ::RightBackwardAction)

Differential of the right action of the SpecialEuclidean group on itself. The formula for the rotation part is the differential of the right rotation action, while the formula for the translation part reads

\[R_q⋅X_R⋅t_p + X_t\]

where $R_q$ is the rotation part of q, $X_R$ is the rotation part of X, $t_p$ is the translation part of p and $X_t$ is the translation part of X.

embed(M::SpecialEuclideanInGeneralLinear, p, X)

Embed the tangent vector X at point p on SpecialEuclidean in the GeneralLinear group. Point p can use any representation valid for SpecialEuclidean. The embedding is similar from the one defined by screw_matrix but the translation part is multiplied by inverse of the rotation part.

embed(M::SpecialEuclideanInGeneralLinear, p)

Embed the point p on SpecialEuclidean in the GeneralLinear group. The embedding is calculated using affine_matrix.

project(M::SpecialEuclideanInGeneralLinear, p, X)

Project tangent vector X at point p in GeneralLinear to the SpecialEuclidean Lie algebra. This reverses the transformation performed by embed

project(M::SpecialEuclideanInGeneralLinear, p)

Project point p in GeneralLinear to the SpecialEuclidean group. This is performed by extracting the rotation and translation part as in affine_matrix.

SpecialLinear{T,𝔽} <: AbstractDecoratorManifold

The special linear group $\mathrm{SL}(n,𝔽)$ that is, the group of all invertible matrices with unit determinant in $𝔽^{n×n}$.

The Lie algebra $𝔰𝔩(n, 𝔽) = T_e \mathrm{SL}(n,𝔽)$ is the set of all matrices in $𝔽^{n×n}$ with trace of zero. By default, tangent vectors $X_p ∈ T_p \mathrm{SL}(n,𝔽)$ for $p ∈ \mathrm{SL}(n,𝔽)$ are represented with their corresponding Lie algebra vector $X_e = p^{-1}X_p ∈ 𝔰𝔩(n, 𝔽)$.

The default metric is the same left-$\mathrm{GL}(n)$-right-$\mathrm{O}(n)$-invariant metric used for GeneralLinear(n, 𝔽). The resulting geodesic on $\mathrm{GL}(n,𝔽)$ emanating from an element of $\mathrm{SL}(n,𝔽)$ in the direction of an element of $𝔰𝔩(n, 𝔽)$ is a closed subgroup of $\mathrm{SL}(n,𝔽)$. As a result, most metric functions forward to GeneralLinear.

project(G::SpecialLinear, p, X)

Orthogonally project $X ∈ 𝔽^{n×n}$ onto the tangent space of $p$ to the SpecialLinear$G = \mathrm{SL}(n, 𝔽)$. The formula reads

\[\operatorname{proj}_{p} = (\mathrm{d}L_p)_e ∘ \operatorname{proj}_{𝔰𝔩(n, 𝔽)} ∘ (\mathrm{d}L_p^{-1})_p \colon X ↦ X - \frac{\operatorname{tr}(X)}{n} I,\]

where the last expression uses the tangent space representation as the Lie algebra.

project(G::SpecialLinear, p)

Project $p ∈ \mathrm{GL}(n, 𝔽)$ to the SpecialLinear group $G=\mathrm{SL}(n, 𝔽)$.

Given the singular value decomposition of $p$, written $p = U S V^\mathrm{H}$, the formula for the projection is

\[\operatorname{proj}_{\mathrm{SL}(n, 𝔽)}(p) = U S D V^\mathrm{H},\]

where

\[D_{ij} = δ_{ij} \begin{cases} 1 & \text{ if } i ≠ n \\ \det(p)^{-1} & \text{ if } i = n \end{cases}.\]

TranslationGroup{T,𝔽} <: GroupManifold{Euclidean{T,𝔽},AdditionOperation}

Translation group $\mathrm{T}(n)$ represented by translation arrays.

Constructor

TranslationGroup(n₁,...,nᵢ; field=𝔽, parameter::Symbol=:type)

Generate the translation group on $𝔽^{n₁,…,nᵢ}$ = Euclidean(n₁,...,nᵢ; field=𝔽), which is isomorphic to the group itself.

LeftInvariantMetric <: AbstractMetric

An AbstractMetric that changes the metric of a Lie group to the left-invariant metric obtained by left-translations to the identity. Adds the HasLeftInvariantMetric trait.

RightInvariantMetric <: AbstractMetric

An AbstractMetric that changes the metric of a Lie group to the right-invariant metric obtained by right-translations to the identity. Adds the HasRightInvariantMetric trait.

direction(::AbstractDecoratorManifold) -> AD

Get the direction of the action a certain Lie group with its implicit metric has.

has_approx_invariant_metric(
    G::AbstractDecoratorManifold,
    p,
    X,
    Y,
    qs::AbstractVector,
    conv::ActionDirectionAndSide = LeftForwardAction();
    kwargs...,
) -> Bool

Check whether the metric on the group $\mathcal{G}$ is (approximately) invariant using a set of predefined points. Namely, for $p ∈ \mathcal{G}$, $X,Y ∈ T_p \mathcal{G}$, a metric $g$, and a translation map $τ_q$ in the specified direction, check for each $q ∈ \mathcal{G}$ that the following condition holds:

\[g_p(X, Y) ≈ g_{τ_q p}((\mathrm{d}τ_q)_p X, (\mathrm{d}τ_q)_p Y).\]

This is necessary but not sufficient for invariance.

Optionally, kwargs passed to isapprox may be provided.

AbstractCartanSchoutenConnection

Abstract type for Cartan-Schouten connections, that is connections whose geodesics going through group identity are one-parameter subgroups. See [PL20] for details.

CartanSchoutenMinus

The unique Cartan-Schouten connection such that all left-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.

CartanSchoutenPlus

The unique Cartan-Schouten connection such that all right-invariant vector fields are globally defined by their value at identity. It is biinvariant with respect to the group operation.

CartanSchoutenZero

The unique torsion-free Cartan-Schouten connection. It is biinvariant with respect to the group operation.

If the metric on the underlying manifold is bi-invariant then it is equivalent to the Levi-Civita connection of that metric.

exp(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, X) where {𝔽}

Compute the exponential map on the ConnectionManifoldM with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [PL20] for details.

log(M::ConnectionManifold{𝔽,<:AbstractDecoratorManifold{𝔽},<:AbstractCartanSchoutenConnection}, p, q) where {𝔽}

Compute the logarithmic map on the ConnectionManifoldM with a Cartan-Schouten connection. See Sections 5.3.2 and 5.3.3 of [PL20] for details.

parallel_transport_direction(M::CartanSchoutenZeroGroup, ::Identity, X, d)

Transport tangent vector X at identity on the group manifold with the CartanSchoutenZero connection in the direction d. See [PL20] for details.

parallel_transport_to(M::CartanSchoutenMinusGroup, p, X, q)

Transport tangent vector X at point p on the group manifold M with the CartanSchoutenMinus connection to point q. See [PL20] for details.

vector_transport_to(M::CartanSchoutenPlusGroup, p, X, q)

Transport tangent vector X at point p on the group manifold M with the CartanSchoutenPlus connection to point q. See [PL20] for details.

parallel_transport_to(M::CartanSchoutenZeroGroup, p::Identity, X, q)

Transport vector X at identity of group M equipped with the CartanSchoutenZero connection to point q using parallel transport.