ο‚›GitHub

Transition from GroupManifolds in Manifolds.jl

One predecessor of LieGroups.jl are the GroupManifolds in Manifolds.jl. While this package provides the same features, one reason for a new package is, that a β€œrestart” offers the opportunity to put the main focus for the functions in this package really on Lie groups.

This tutorial provides an overview of the necessary changes to your code if you based it on the predecessor.

Table of function names and its successors

The following table lists all functions related to GroupManifolds and their new names or replacements here in LieGroups.jl. In this code G always refers to the GroupManifold in the first column and the LieGroup in the second. Lie group elements (points) are always g,h, Lie algebra elements (vectors) always X, Y.

New functions and types in this package are only mentioned, if they are worth a comment and if something changed.

The list is alphabetical, but first lists types, then functions

Manifolds.jlLieGroups.jlComment
AdditionOperationAdditionGroupOperation
LeftForwardActionLeftGroupOperationAction
LeftBackwardActionInverseRightGroupOperationActionnote that this is now also aa AbstractLeftGroupActionType
LieAlgebra(G)new alias to emphasize its manifold- and vector structure as well as for a few dispatch methods.
GroupManifold(M, op)LieGroup(M, op)
PowerGroup(M)PowerLieGroup(G,n)The main change is, that the constructor now requires a Lie group to build the power Lie group; This also allows for G^n. The other two former constructors for nested and nested-replacing are no longer necessary. PowerLieGroup behaves exactly the same as PowerManifold.
ProductGroup(M)ProductLieGroup(G, H)The main change is, that the constructor now requires two Lie groups to build their product. This also allows for the short hand GΓ—H to generate this product.
RightBackwardActionRightGroupOperationAction
RightForwardActionInverseLeftGroupOperationActionnote that this is an AbstractRightGroupActionType
SemidirectProductGroup(G, H, a)LeftSemidirectProductLieGroup(G, H, a)While this staid the same, there is now also the default_left_action(G,H). When this agrees with a you can use the short hand G⋉H to generate this semidirect product. Analogously there now also exists the RightSemidirectProductLieGroup(G,H) withdefault_left_action(G,H) that allows for the short cut Gβ‹ŠH
SpecialEuclidean(n)SpecialEuclideanGroup(n; variant=:right)
adjoint_actionadjointnow implemented with a default, when you provide diff_conjugate!.
apply_diffdiff_applymodifiers (diff) come first, consistent with ManifoldsDiff.jl
apply_diff_groupdiff_group_applymodifiers (diff/group) come first, consistent with ManifoldsDiff.jl
conjugate, diff_conjugatea new function to model $c_g: \mathcal G β†’ \mathcal G$ given by $c_g(h) = g∘h∘g^{-1}$
differential_exp_argument_lie_approx-Scheduled for update and renaming. Though available in ManifoldDiff.jl for GroupManifolds, that will move to differential_exp_argument_approx instead, since exp_lie changed to now just exp.
exp(G, g, X)exp(base_manifold(G), g, X)the previous defaults whenever not agreeing with the Riemannian one can now be accessed on the internal manifold
exp_inv(G, g, X)exp(G, g, X)the exponential map invariant to the group operation is the default on Lie groups here
exp_lie(G, X)exp(G, X)the (matrix/Lie group) exponential
inner(G, g, X, Y)inner(LieAlgebra(G), X, Y)the inner product on the Lie Algebra. The old variant still calls the new one.
inverse_translate(G, g, h, c)inv_left_compose(G, g, h), inv_right_compose(G, g, h)compute $g^{-1}∘h$ and $g∘h^{-1}$, resp.
inverse_translate_diff(G, g, h, X, LeftForwardAction())-discontinued, use diff_left_compose(G, inv(G,g), h)
inverse_translate_diff(G, g, h, X, RightBackwardAction())-discontinued, use diff_left_compose(G, h, inv(G,g))
log(G, g, h)log(base_manifold(G), g, h)you can now access the previous defaults on the internal manifold whenever they do not agree with the invariant one
log_inv(G, g, h)log(G, g, h)the logarithmic map invariant to the group operation is the default on Lie groups here
log_lie(G, g)log(G, g)the (matrix/Lie group) logarithm
norm(G, p, X)norm(LieAlgebra(G), X)the norm product on the Lie Algebra. The old variant still calls the new one.
switch_direction(A)inv(A)switches from an action to its inverse action (formerly the direction forward/backward, sometimes even left/right, do not confuse with the side left/right).
switch_side(A)switch(A)switches from a left action to its corresponding right action.
translate(G, g, h)compose(G, g, h)unified to compose
translate_diff(G, g, X, c)diff_left_compose(G, g, h, X), diff_right_compose(G, g, h, X)for compose $g∘h$ the functions now specify whether the derivative is taken w.r.t. to the left (g) or right (h) argument
VeeOrthogonalBasisDefaultLieAlgebraOrthogonalBasis

Further notable changes

  1. In general the default for tangent vectors is now to represent them in the LieAlgebra, which obtains its own name now, though defined as a constant of a certain tangent space.
  2. In accordance with point 1., the GeneralLinearGroup (formerly GeneralLinear) switched to using its Lie algebra to represent tangent vectors.
  3. Formerly, both a power manifold of Lie groups as a manifold as well as a Lie group of a power manifold as a Lie group were possible. This is unified to just defining G^n as the Lie group on the power manifold with the element-wise group operation.
  4. Formerly, product manifolds were stored as a ProductManifold of Lie groups and an indicator for the group operation, that the direct product should be used. This is switched to internally only store a ProductManifold as well as a (new) ProductGroupOperation that specifies one group operation for every factor.
  5. The last two points achieve one unified modelling aspect of Lie groups: they are now always a manifold M together with a group operation op, but a Lie group does not store another Lie group (or product of them) internally with one common type they share, a LieGroup.
  6. Formerly, identity_element(group[, gT]) to provide a materialized version of the Identity point on a Lie group accepted either a concrete point g on the Lie group or the Type T of g. This is now unified for example with zero_vector and only accepts a Type as second argument.
  7. There are two usual representations of the SpecialEuclideanGroup, one with the rotation matrix on the left and the translation vector on the right and vice versa. The default is now to have the rotation matrix on the left, while formerly it was on the right. To be precise, SpecialEuclideanGroup(3) is now equivalent to SpecialOrthogonalGroup(3) ⋉ TranslationGroup(3). To get the previous default use SpecialEuclideanGroup(; variant=:right) which is the same as writing TranslationGroup(3) β‹Š SpecialOrthogonalGroup(3).