An interface for Lie groups

AbstractLieGroup{𝔽, O<:AbstractGroupOperation, M<:AbstractManifold{𝔽}} <: AbstractManifold{𝔽}

An abstract type to represent Lie groups. For most cases it should suffice to “combine” an AbstractManifold with an AbstractGroupOperation, see LieGroup.

LieGroup{𝔽, O<:AbstractGroupOperation, M<:AbstractManifold{𝔽}} <:  AbstractLieGroup{𝔽, O, M}

Represent a Lie Group $\mathcal G$.

A Lie Group $\mathcal G$ is a group endowed with the structure of a manifold such that the group operations $∘: \mathcal G×\mathcal G → \mathcal G$, see compose and the inverse operation $⋅^{-1}: \mathcal G → \mathcal G$, see inv are smooth, see for example [HN12, Definition 9.1.1].

Lie groups are named after the Norwegian mathematician Marius Sophus Lie (1842–1899).

Fields

• manifold: an AbstractManifold $\mathcal M$
• op: an AbstractGroupOperation $∘$ on that manifold

Constructor

LieGroup(M::AbstractManifold, op::AbstractGroupOperation)

Generate a Lie group based on a manifold M and a group operation op, where vectors by default are stored in the Lie Algebra.

AbstractLieAlgebraTangentVector <: ManifoldsBase.AbstractTangentVector

An abstract type for a tangent vector represented in a LieAlgebra.

While an tangent vectors are usually kept untyped for flexibility, it might be necessary to distinguish different types of points, for example

• for complicated representations that require a struct

@ semantic verification

• when there exist different representations

By sub-typing the AbstractManifoldPoint, this follows the same idea as in ManifoldsBase.jl.

AbstractLieGroupPoint <: ManifoldsBase.AbstractManifoldPoint end

An abstract type for a point on an AbstractLieGroup. While an points and tangent vectors are usually kept untyped for flexibility, it might be necessary to distinguish different types of points, for example

• for complicated representations that require a struct
• semantic verification
• when there exist different representations

By sub-typing the AbstractManifoldPoint, this follows the same idea as in ManifoldsBase.jl.

adjoint(G::AbstractLieGroup, g, X)
adjoint!(G::AbstractLieGroup, Y, g, X)

Compute the adjoint $\mathrm{Ad}(g): \mathfrak g → \mathfrak g$, which is defined as the differential diff_conjugate of the conjugate $c_g(h) = g∘h∘g^{-1}$ evaluated at the Identity $h=\mathrm{e}$. The operation can be performed in-place of Y.

\[ \mathrm{Ad}(g)[X] = D c_g(\mathrm{e}) [X], \qquad X ∈ \mathfrak g.\]

see [HN12, Section 9.2.3].

On matrix Lie groups the adjoint reads $\mathrm{Ad}(g)[X] = g∘X∘g^{-1}$.

exp(G::AbstractLieGroup, g, X)
exp!(G::AbstractLieGroup, h, g, X)

Compute the Lie group exponential map for $g∈\mathcal G$ and $X∈\mathfrak g$, where $\mathfrak g$ denotes the LieAlgebra of $\mathcal G$. It is given by

\[\exp_g X = g∘\exp_{\mathcal G}(X)\]

where X can be scaled by t, the computation can be performed in-place of h, and $\exp_{\mathcal G}$ denotes the Lie group exponential function.

If g is the Identity the Lie group exponential function $\exp_{\mathcal G}$ is computed directly. Implementing the Lie group exponential function introduces a default implementation with the formula above.

exp(G::AbstractLieGroup, X::T)
exp!(G::AbstractLieGroup, g, X)

Compute the (Lie group) exponential function

\[\exp_{\mathcal G}: \mathfrak g → \mathcal G,\qquad \exp_{\mathcal G}(X) = γ_X(1),\]

where $γ_X$ is the unique solution of the initial value problem

\[γ(0) = \mathrm{e}, \quad γ'(s) = γ(s)⋅X.\]

See also [HN12, Definition 9.2.2]. On matrix Lie groups this is the same as the matrix exponential.

The computation can be performed in-place of g.

inv(G::AbstractLieGroup, g)
inv!(G::AbstractLieGroup, h, g)

Compute the inverse group element $g^{-1}$ with respect to the AbstractGroupOperation $∘$ on the AbstractLieGroup $\mathcal G$, that is, return the unique element $h=g^{-1}$ such that $h∘g=\mathrm{e}$, where $\mathrm{e}$ denotes the Identity.

This can be done in-place of h, without side effects, that is you can do inv!(G, g, g).

isapprox(M::AbstractLieGroup, g, h; kwargs...)

Check if points g and h from AbstractLieGroup are approximately equal. this function calls the corresponding isapprox on the AbstractManifold after handling the cases where one or more of the points are the Identity. All keyword argments are passed to this function as well.

log(G::AbstractLieGroup, g, h)
log!(G::AbstractLieGroup, X, g, h)

Compute the Lie group logarithmic map $\log_g: \mathcal G → \mathfrak g$, where $\mathfrak g$ denotes the LieAlgebra of $\mathcal G$. It is given by

\[\log_g h = \log_{\mathcal G}(g^{-1}∘h)\]

where $\log_{\mathcal G}$ denotes the Lie group logarithmic function The computation can be performed in-place of X.

log(G::AbstractLieGroup, g, h)
log(G::AbstractLieGroup, g)
log(G::AbstractLieGroup, g::Identity, T)
log!(G::AbstractLieGroup, X::T, g)

Compute the (Lie group) logarithmic function $\log_{\mathcal G}: \mathcal G → \mathfrak g$, which is the inverse of the Lie group exponential function. For the allocating variant, you can specify the type T, when the point argument is the identity and hence does not provide the representation used. The computation can be performed in-place of X::T, which then determines the type.

rand(::AbstractLieGroup; vector_at=nothing, σ::Real=1.0, kwargs...)
rand(::AbstractLieGroup, PT::Type; vector_at=nothing, σ::Real=1.0, kwargs...)
rand!(::LieAlgebra, T::Type; σ::Real=1.0, kwargs...)
rand!(::AbstractLieGroup, gX::PT; vector_at=nothing, σ::Real=1.0, kwargs...)
rand!(::LieAlgebra, X::T; σ::Real=1.0, 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, see also rand(::LieAlgebra; kwargs...)

For both cases, you can provide the type $T$ for the tangent vector and/or point $PT$, if you want to generate a random point in a certain representation. For the in-place variants the type is inferred from pX´ andX`, respectively.

rand(::AbstractLieGroup; vector_at=nothing, σ::Real=1.0, kwargs...)
rand(::AbstractLieGroup, PT::Type; vector_at=nothing, σ::Real=1.0, kwargs...)
rand!(::LieAlgebra, T::Type; σ::Real=1.0, kwargs...)
rand!(::AbstractLieGroup, gX::PT; vector_at=nothing, σ::Real=1.0, kwargs...)
rand!(::LieAlgebra, X::T; σ::Real=1.0, 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, see also rand(::LieAlgebra; kwargs...)

For both cases, you can provide the type $T$ for the tangent vector and/or point $PT$, if you want to generate a random point in a certain representation. For the in-place variants the type is inferred from pX´ andX`, respectively.

compose(G::AbstractLieGroup, g, h)
compose!(G::AbstractLieGroup, k, g, h)

Perform the group operation $g ∘ h$ for two $g, h ∈ \mathcal G$ on the AbstractLieGroup G. This can also be done in-place of h.

conjugate(G::AbstractLieGroup, g, h)
conjugate!(G::AbstractLieGroup, k, g, h)

Compute the conjugation map $c_g: \mathcal G → \mathcal G$ given by $c_g(h) = g∘h∘g^{-1}$. This can be done in-place of k.

conjugate(G::AbstractLieGroup, g, h)
conjugate!(G::AbstractLieGroup, k, g, h)

Compute the conjugation map $c_g: \mathcal G → \mathcal G$ given by $c_g(h) = g∘h∘g^{-1}$. This can be done in-place of k.

diff_conjugate(G::AbstractLieGroup, g, h, X)
diff_conjugate!(G::AbstractLieGroup, Y, g, h, X)

Compute the differential of the conjugate $c_g(h) = g∘h∘g^{-1}$ on the AbstractLieGroup G. The operation can be performed in-place of Y.

\[ D(c_g(h))[X], \qquad X ∈ \mathfrak g.\]

diff_conjugate(G::AbstractLieGroup, g, h, X)
diff_conjugate!(G::AbstractLieGroup, Y, g, h, X)

Compute the differential of the conjugate $c_g(h) = g∘h∘g^{-1}$ on the AbstractLieGroup G. The operation can be performed in-place of Y.

\[ D(c_g(h))[X], \qquad X ∈ \mathfrak g.\]

diff_inv(G::AbstractLieGroup, g, X)
diff_inv!(G::AbstractLieGroup, Y, g, X)

Compute the differential of the function $ι_{\mathcal G}(g) = g^{-1}$, where $Dι_{\mathcal G}(g): \mathfrak g → \mathfrak g$. This can be done in-place of Y.

diff_inv(G::AbstractLieGroup, g, X)
diff_inv!(G::AbstractLieGroup, Y, g, X)

Compute the differential of the function $ι_{\mathcal G}(g) = g^{-1}$, where $Dι_{\mathcal G}(g): \mathfrak g → \mathfrak g$. This can be done in-place of Y.

diff_left_compose(G::AbstractLieGroup, g, h, X)
diff_left_compose!(G::AbstractLieGroup, Y, g, h, X)

Compute the differential of the left group multiplication $λ_g(h) = g∘h$, on the AbstractLieGroup G, that is Compute $Dλ_g(h)[X]$, $X ∈ 𝔤$. This can be done in-place of Y.

diff_left_compose(G::AbstractLieGroup, g, h, X)
diff_left_compose!(G::AbstractLieGroup, Y, g, h, X)

Compute the differential of the left group multiplication $λ_g(h) = g∘h$, on the AbstractLieGroup G, that is Compute $Dλ_g(h)[X]$, $X ∈ 𝔤$. This can be done in-place of Y.

diff_right_compose(G::AbstractLieGroup, h, g, X)
diff_right_compose!(G::AbstractLieGroup, Y, h, g, X)

Compute the differential of the right group multiplication $ρ_g(h) = h∘g$, on the AbstractLieGroup G, that is Compute $Dρ_g(h)[X]$, $X ∈ 𝔤$ This can be done in-place of Y.

diff_right_compose(G::AbstractLieGroup, h, g, X)
diff_right_compose!(G::AbstractLieGroup, Y, h, g, X)

Compute the differential of the right group multiplication $ρ_g(h) = h∘g$, on the AbstractLieGroup G, that is Compute $Dρ_g(h)[X]$, $X ∈ 𝔤$ This can be done in-place of Y.

identity_element(G::AbstractLieGroup)
identity_element(G::AbstractLieGroup, T)
identity_element!(G::AbstractLieGroup, e::T)

Return a point representation of the Identity on the AbstractLieGroup G. By default this representation is the default array or number representation. If there exist several representations, the type T can be used to distinguish between them, and it should be provided for both the AbstractLieGroupPoint as well as the AbstractLieAlgebraTangentVector if they differ, since maybe only one of these types might be available for the second signature.

It returns the corresponding default representation of $e$ as a point on G. This can be performed in-place of e.

inv(G::AbstractLieGroup, g)
inv!(G::AbstractLieGroup, h, g)

Compute the inverse group element $g^{-1}$ with respect to the AbstractGroupOperation $∘$ on the AbstractLieGroup $\mathcal G$, that is, return the unique element $h=g^{-1}$ such that $h∘g=\mathrm{e}$, where $\mathrm{e}$ denotes the Identity.

This can be done in-place of h, without side effects, that is you can do inv!(G, g, g).

inv_left_compose(G::AbstractLieGroup, g, h)
inv_left_compose!(G::AbstractLieGroup, k, g, h)

Compute the inverse of the left group operation $λ_g(h) = g∘h$, on the AbstractLieGroup G, that is, compute $λ_g^{-1}(h) = g^{-1}∘h$. This can be done in-place of k.

inv_left_compose(G::AbstractLieGroup, g, h)
inv_left_compose!(G::AbstractLieGroup, k, g, h)

Compute the inverse of the left group operation $λ_g(h) = g∘h$, on the AbstractLieGroup G, that is, compute $λ_g^{-1}(h) = g^{-1}∘h$. This can be done in-place of k.

inv_right_compose(G::AbstractLieGroup, h, g)
inv_right_compose!(G::AbstractLieGroup, k, h, g)

Compute the inverse of the right group operation $ρ_g(h) = h∘g$, on the AbstractLieGroup G, that is compute $ρ_g^{-1}(h) = h∘g^{-1}$. This can be done in-place of k.

inv_right_compose(G::AbstractLieGroup, h, g)
inv_right_compose!(G::AbstractLieGroup, k, h, g)

Compute the inverse of the right group operation $ρ_g(h) = h∘g$, on the AbstractLieGroup G, that is compute $ρ_g^{-1}(h) = h∘g^{-1}$. This can be done in-place of k.

jacobian_conjugate(G::AbstractLieGroup, g, h; basis::AbstractBasis=DefaultLieAlgebraOrthogonalBasis(); X=zero_vector(LieAlgebar(G)))
jacobian_conjugate!(G::AbstractLieGroup, J, g, h; basis::AbstractBasis=DefaultLieAlgebraOrthogonalBasis(); X=zero_vector(LieAlgebar(G)))

Compute the Jacobian of the conjugate $c_g(h) = g∘h∘g^{-1}$, with respect to an AbstractBasis of the LieAlgebra.

A default is implemented using diff_conjugate $D(c_g(h))[X]$: the $j$th column of of the Jacobian matrix $J$ are given by the coefficients of the tangent vector D(c_g(h))[X_j]with respect to the basisB, whereX_jis thejth basis vector ofB`.

Keyword arguments

• X=zero_vector(LieAlgebra(G)) pass an interims memory to store the Lie algebra tangent vector in.

jacobian_conjugate(G::AbstractLieGroup, g, h; basis::AbstractBasis=DefaultLieAlgebraOrthogonalBasis(); X=zero_vector(LieAlgebar(G)))
jacobian_conjugate!(G::AbstractLieGroup, J, g, h; basis::AbstractBasis=DefaultLieAlgebraOrthogonalBasis(); X=zero_vector(LieAlgebar(G)))

Compute the Jacobian of the conjugate $c_g(h) = g∘h∘g^{-1}$, with respect to an AbstractBasis of the LieAlgebra.

A default is implemented using diff_conjugate $D(c_g(h))[X]$: the $j$th column of of the Jacobian matrix $J$ are given by the coefficients of the tangent vector D(c_g(h))[X_j]with respect to the basisB, whereX_jis thejth basis vector ofB`.

Keyword arguments

• X=zero_vector(LieAlgebra(G)) pass an interims memory to store the Lie algebra tangent vector in.

adjoint(G::AbstractLieGroup, g, X)
adjoint!(G::AbstractLieGroup, Y, g, X)

Compute the adjoint $\mathrm{Ad}(g): \mathfrak g → \mathfrak g$, which is defined as the differential diff_conjugate of the conjugate $c_g(h) = g∘h∘g^{-1}$ evaluated at the Identity $h=\mathrm{e}$. The operation can be performed in-place of Y.

\[ \mathrm{Ad}(g)[X] = D c_g(\mathrm{e}) [X], \qquad X ∈ \mathfrak g.\]

see [HN12, Section 9.2.3].

On matrix Lie groups the adjoint reads $\mathrm{Ad}(g)[X] = g∘X∘g^{-1}$.

compose(G::AbstractLieGroup, g, h)
compose!(G::AbstractLieGroup, k, g, h)

Perform the group operation $g ∘ h$ for two $g, h ∈ \mathcal G$ on the AbstractLieGroup G. This can also be done in-place of h.

identity_element(G::AbstractLieGroup)
identity_element(G::AbstractLieGroup, T)
identity_element!(G::AbstractLieGroup, e::T)

Return a point representation of the Identity on the AbstractLieGroup G. By default this representation is the default array or number representation. If there exist several representations, the type T can be used to distinguish between them, and it should be provided for both the AbstractLieGroupPoint as well as the AbstractLieAlgebraTangentVector if they differ, since maybe only one of these types might be available for the second signature.

It returns the corresponding default representation of $e$ as a point on G. This can be performed in-place of e.

is_identity(G::AbstractLieGroup, q; kwargs...)

Check whether q is the identity on the AbstractLieGroup $\mathcal G$. This means it is either the Identity{O} with the respect to the corresponding AbstractGroupOperation O, or (approximately) the correct point representation.

See also

identity_element, identity_element!

base_manifold(G::AbstractLieGroup)

Return the manifold stored within the AbstractLieGroup G.

exp(G::AbstractLieGroup, g, X)
exp!(G::AbstractLieGroup, h, g, X)

Compute the Lie group exponential map for $g∈\mathcal G$ and $X∈\mathfrak g$, where $\mathfrak g$ denotes the LieAlgebra of $\mathcal G$. It is given by

\[\exp_g X = g∘\exp_{\mathcal G}(X)\]

where X can be scaled by t, the computation can be performed in-place of h, and $\exp_{\mathcal G}$ denotes the Lie group exponential function.

If g is the Identity the Lie group exponential function $\exp_{\mathcal G}$ is computed directly. Implementing the Lie group exponential function introduces a default implementation with the formula above.

exp(G::AbstractLieGroup, X::T)
exp!(G::AbstractLieGroup, g, X)

Compute the (Lie group) exponential function

\[\exp_{\mathcal G}: \mathfrak g → \mathcal G,\qquad \exp_{\mathcal G}(X) = γ_X(1),\]

where $γ_X$ is the unique solution of the initial value problem

\[γ(0) = \mathrm{e}, \quad γ'(s) = γ(s)⋅X.\]

See also [HN12, Definition 9.2.2]. On matrix Lie groups this is the same as the matrix exponential.

The computation can be performed in-place of g.

is_point(G::AbstractLieGroup, g; kwargs...)

Check whether g is a valid point on the Lie Group G. This falls back to checking whether g is a valid point on the base_manifoldG. unless g is an Identity. Then, it is checked whether it is the identity element corresponding to G.

log(G::AbstractLieGroup, g, h)
log!(G::AbstractLieGroup, X, g, h)

Compute the Lie group logarithmic map $\log_g: \mathcal G → \mathfrak g$, where $\mathfrak g$ denotes the LieAlgebra of $\mathcal G$. It is given by

\[\log_g h = \log_{\mathcal G}(g^{-1}∘h)\]

where $\log_{\mathcal G}$ denotes the Lie group logarithmic function The computation can be performed in-place of X.

log(G::AbstractLieGroup, g, h)
log(G::AbstractLieGroup, g)
log(G::AbstractLieGroup, g::Identity, T)
log!(G::AbstractLieGroup, X::T, g)

Compute the (Lie group) logarithmic function $\log_{\mathcal G}: \mathcal G → \mathfrak g$, which is the inverse of the Lie group exponential function. For the allocating variant, you can specify the type T, when the point argument is the identity and hence does not provide the representation used. The computation can be performed in-place of X::T, which then determines the type.

rand(::AbstractLieGroup; vector_at=nothing, σ::Real=1.0, kwargs...)
rand(::AbstractLieGroup, PT::Type; vector_at=nothing, σ::Real=1.0, kwargs...)
rand!(::LieAlgebra, T::Type; σ::Real=1.0, kwargs...)
rand!(::AbstractLieGroup, gX::PT; vector_at=nothing, σ::Real=1.0, kwargs...)
rand!(::LieAlgebra, X::T; σ::Real=1.0, 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, see also rand(::LieAlgebra; kwargs...)

For both cases, you can provide the type $T$ for the tangent vector and/or point $PT$, if you want to generate a random point in a certain representation. For the in-place variants the type is inferred from pX´ andX`, respectively.

CommonUnitarySubAlgebra{𝔽,T}

A constant that allows to refer to several sub Algebras of $\mathfrak u(n)$ for implementations where

• certain sub algebras real/complex share a common implementation, e.g. for the same sizes T usually via TypeParameter
• certain functions are the same for all sizes T as long as the field 𝔽 is the same

default_lie_group_fallbacks(TG, TF, TP, TV, pfield::Symbol, Xfield::Symbol, groupOp)

Introduce default fallbacks for all basic functions on Lie groups, for Lie group of type TG with group operation Op, points of type TP, tangent vectors of type TV, with forwarding to fields pfield and Xfield for point and tangent vector functions, respectively.

ValidationLieGroup{L<:AbstractLieGroup} <: AbstractLieGroup

A Lie group to add tests to input parameters and output values of functions defined for LieGroups.

Using the ignore_contexts keyword allows to specify a single Symbol or a vector of Symbols Of which contexts to ignore.

Current contexts are

• :All: disable all checks
• :Point: checks for points
• :Algebra: checks related to the LieAlgebra
• :Output: checks for output
• :Input: checks for input variables

Fields

• lie_group::L the AbstractLieGroup to be decorated
• mode::Symbol: The mode to be used for error handling, either :error or :warn
• ignore_contexts::AbstractVector{Symbol}: store contexts to be ignored of validation.
• ignore_functions::Dict{<:Function,<:Union{Symbol,<:AbstractVector{Symbol}}: store contexts to be ignored with in a function or its mutating variant.

where all but the first field are analogous to the setups of the ValidationManifold. We refer to those docs for more examples on their meaning.

Constructor

ValidationLieGroup(L::AbstractLieGroup, check_manifold=true; kwargs...)

Generate the Validation Lie Group for the given AbstractLieGroup L. If check_manifold is set to true the inner manifold is additionally wrapped in a ValidationManifold. All suitable keywords are passed to the constructor of the validation manifold as well.

Keyword arguments

• error::Symbol=:error: specify how errors in the validation should be reported. this is passed to is_point and is_vector as the error keyword argument. Available values are :error, :warn, :info, and :none. Every other value is treated as :none.
• ignore_contexts = Vector{Symbol}() a vector to indicate which validation contexts should not be performed.
• ignore_functions=Dict{Function,Union{Symbol,Vector{Symbol}}}() a dictionary to disable certain contexts within functions. The key here is the non-mutating function variant (if it exists). The contexts are the same as in ignore_contexts.

_vLc(M::ValidationLieGroup, f::Function, context::Symbol)
_vLc(M::ValidationLieGroup, f::Function, context::NTuple{N,Symbol}) where {N}
_vLc(M::ValidationLieGroup, ::Nothing, context::NTuple{N,Symbol}) where {N}

Return whether a check should be performed within f and the context(s) provided, if the second argument is :Nothing, only the context is checked

This function returns false and hence indicates not to check, when

• (one of the) context(s) is in the ignore list for f within ignore_functions
• (one of the) context(s) is in the ignore_contexts list

Otherwise the test is active.

!!! Note This function is internal and used very often, so it has a very short name; _vLc stands for "ValidationLieGroup check".

_msg(G::ValidationLieGroup, str; error=:None, within::Union{Nothing,<:Function} = nothing,
context::Union{NTuple{N,Symbol} where N} = NTuple{0,Symbol}())

issue a message str according to the mode mode (as @error, @warn, @info).