Introduce the general linear group and the multiplication group opera…

…tion. (#12) * Initial commit. * Setup GeneralLinear. * Starts a bit towards multiplication groups. * Rename a tutorial, start test suite for GLn * Bump dependencies and remove a function that is now available in ManifoldsBase. --------- Co-authored-by: Mateusz Baran <mateuszbaran89@gmail.com> Co-authored-by: Johannes Terblanche <6612981+Affie@users.noreply.github.com>
JuliaManifolds · Nov 3, 2024 · 4233975 · 4233975
1 parent c695564
commit 4233975
Show file tree

Hide file tree

Showing 32 changed files with 1,298 additions and 75 deletions.
diff --git a/.codecov.yml b/.codecov.yml
@@ -0,0 +1,2 @@
+ignore:
+  - "src/documentation_glossary.jl" # exclude this since it is just use to create the docs and code cov goes bogus on this.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,13 +1,13 @@
 name: CI
 on:
   push:
-    branches: [master]
+    branches: [main]
     tags: [v*]
   pull_request:
 
 jobs:
   test:
-    name: Julia ${{ matrix.julia-version }} - ${{ matrix.group }} - ${{ matrix.os }}
+    name: Julia ${{ matrix.julia-version }} - ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:

diff --git a/.github/workflows/documenter.yml b/.github/workflows/documenter.yml
@@ -1,7 +1,7 @@
 name: Documenter
 on:
   push:
-    branches: [master]
+    branches: [main]
     tags: [v*]
   pull_request:
 

diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml
@@ -1,7 +1,7 @@
 name: Format
 on:
   push:
-    branches: [master]
+    branches: [main]
     tags: [v*]
   pull_request:
 

diff --git a/.vale.ini b/.vale.ini
@@ -14,6 +14,5 @@ BasedOnStyles = Vale, Google
 Google.Will = false ; given format and really with intend a _will_
 Google.Headings = false ; some might jeally ahabe [] in their headers
 
-
 [*.jl]
 BasedOnStyles = Vale, Google, write-good
diff --git a/NEWS.md b/NEWS.md
@@ -5,42 +5,47 @@ All notable Changes to the Julia package `LieGroups.jl` will be documented in th
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] unreleased
+## [0.1.0] – unreleased
 
 Everything denoted by “formerly” refers to the previous name in [`Manifolds.jl`](https://juliamanifolds.github.io/Manifolds.jl/stable/).
 
 ### Added
 
 * `LieAlgebra`
 * `LieGroup` (formerly `GroupManifold`) as well as the concrete groups
-  * `AdditiveGroup` (formerly `TranslationGroup`)
+  * `TranslationGroup`
+  * `GeneralLinearGroup` (formerly `GeneralLinear`)
 * `AbstractGroupOperation` as well as its concrete subtypes
   * `AdditionGroupOperation` (formerly `AdditionOperation`)
-* `AbstractGroupActionType` with its 2 specific (new) abstract
+* `AbstractGroupActionType` with its 2 specific (new) abstract subtypes
   * `AbstractLeftGroupActionType`
   * `AbstractRightGroupActionType`
 * For the group operation actions there are now
   * `LeftGroupOperation` (formerly `LeftForwardAction`)
   * `RightGroupOperation` (formerly `RightBackwardAction`)
   * `InverseLeftGroupOperation` (formerly `RightForwardAction`)
   * `InverseRightGroupOperation` (formerly `LeftBackwardAction`)
+* `LieAlgebraOrthogonalBasis` (replaces `VeeOrthogonalBasis`, which is still available in `ManifoldsBase.jl`)
+* `Identity`
 * `apply`and `apply!`
 * `base_manifold` to access the manifold within a Lie group
 * `compose` and `compose!`
 * `conjugate` and `conjugate!`
 * `diff_apply`, `diff_apply!`, `diff_group_apply`, and `diff_group_apply!` (formerly `apply_diff_[group][!]`)
+* `diff_conjugate` and `diff_conjugate!`
 * `diff_left_compose`, `diff_left_compose!`, `diff_right_compose`, `diff_right_compose!` (formerly `translate_diff` with different sides)
 * `exp(G::LieGroup, g, X)` and `exp!(G::LieGroup, h, g, X)` (formerly `exp_inv` and `exp_inv!`)
 * `exp(G::LieGroup, ::Identity, X)` and `exp!(G::LieGroup, h, ::Identity, X)` (formerly `exp_lie` and `exp_lie!`)
-* `Identity`
-* `idenity_element` and `identity_element!`
+* `hat` and `hat!`, with slightly different signatures, since the base point is omitted.
+* `identity_element` and `identity_element!`
 * `inv` and `inv!` (`inv(::AbstractGroupAction)` was formerly `switch_direction`)
 * `inv_left_compose`, `inv_left_compose!` and `inv_right_compose`, `inv_right_compose!` (these functions correspond to `inverse_translate` with corresponding direction and side)
 * `is_identity`
-* `Lie_bracket` and `Lie_bracket!` (formerly `lie_bracket`)
+* `lie_bracket` and `lie_bracket!`
 * `log(G::LieGroup, g, h)` and `log!(G::LieGroup, X, g, h)` (formerly `log_inv` and `log_inv!`)
 * `log(G::LieGroup, ::Identity, g)` and `log!(G::LieGroup, X, ::Identity, g)` (formerly `log_lie` and `log_lie!`)
 * `switch` (formerly `switch_side`)
+* `vee` and `vee!`, with slightly different signatures, since the base point is omitted.
 
 Compared to `Manifolds.jl`
 * all `translate` functions are not implemented here, since you can just use `compose`. The differentials are implemented as listed above with respect to both left and right argument of compose

diff --git a/Project.toml b/Project.toml
@@ -1,18 +1,20 @@
 name = "LieGroups"
 uuid = "6774de46-80ba-43f8-ba42-e41071ccfc5f"
-authors = ["Seth Axen <seth.axen@gmail.com>", "Mateusz Baran <mateuszbaran89@gmail.com>", "Ronny Bergmann <git@ronnybergmann.net>", "Yueh-Hua Tu", "Olivier Verdier <olivier.verdier@gmail.com>" ]
+authors = ["Seth Axen <seth.axen@gmail.com>", "Mateusz Baran <mateuszbaran89@gmail.com>", "Ronny Bergmann <git@ronnybergmann.net>", "Yueh-Hua Tu", "Olivier Verdier <olivier.verdier@gmail.com>"]
 version = "0.1.0"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Manifolds = "1cead3c2-87b3-11e9-0ccd-23c62b72b94e"
 ManifoldsBase = "3362f125-f0bb-47a3-aa74-596ffd7ef2fb"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 
 [compat]
 Aqua = "0.8"
 LinearAlgebra = "1.6"
-Manifolds = "0.10"
-ManifoldsBase = "0.15.16"
+Manifolds = "0.10.5"
+ManifoldsBase = "0.15.20"
+Random = "1.6"
 Test = "1.6"
 julia = "1.6"
 

diff --git a/Readme.md b/Readme.md
@@ -5,11 +5,16 @@
     </picture>
 </div>
 
-[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliamanifolds.github.io/Manifolds.jl/latest/)
+[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliamanifolds.github.io/LieGroups.jl/dev/)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle) [![CI](https://github.com/JuliaManifolds/LieGroups.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/JuliaManifolds/LieGroups.jl/actions?query=workflow%3ACI+branch%3Amain) [![codecov.io](http://codecov.io/github/JuliaManifolds/LieGroups.jl/coverage.svg?branch=main)](https://codecov.io/gh/JuliaManifolds/LieGroups.jl/)
 
 This is a package to rework the Lie group features of [`Manifolds.jl`](https://juliamanifolds.github.io/Manifolds.jl/stable/) in a unified way into a separate package.
 
+> [!NOTE]
+> Since this is a rework of the features from [`Manifolds.jl`](https://juliamanifolds.github.io/Manifolds.jl/stable/), both `LieGroups.jl` and `Manifolds.jl` 0.10 export a few types of same name, for example `Identity`.
+While `LieGroups.jl` depends on `Manifolds.jl`, it is not recommended to load both into the same namespace, that is, doing `using Manifolds.jl, LieGroups.jl`, since then these conflicts might lead to unforeseen errors, where you would need to specify the namespace to resolve this ambiguity.
+> See [transition from Manifolds.jl](https://juliamanifolds.github.io/LieGroups.jl/stable/tutorials/transition-from-manifoldsjl.html) for a comprehensive list.
+
 This especially also includes a few different choices in default behaviour that
 is different from the [`Manifolds.jl`](https://juliamanifolds.github.io/Manifolds.jl/stable/) one. For purely manifold-based operations, any Lie group still is “build upon” a Riemannian manifold.
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -99,7 +99,11 @@ for (md_file, doc_file) in [("CONTRIBUTING.md", "contributing.md"), ("NEWS.md",
 end
 
 ## Build tutorials menu
-tutorials_menu = "How to..." => ["Get started with Lie Groups" => "index.md"]
+tutorials_menu =
+    "How to..." => [
+        "🚀 Get Started with LieGroups.jl" => "tutorials/getstarted.md",
+        "Transition from `GroupManifolds`" => "tutorials/transition.md",
+    ]
 # (e) finally make docs
 bib = CitationBibliography(joinpath(@__DIR__, "src", "references.bib"); style=:alpha)
 links = InterLinks(
@@ -118,16 +122,17 @@ makedocs(;
         "Home" => "index.md",
         "About" => "about.md",
         (tutorials_in_menu ? [tutorials_menu] : [])...,
+        "Lie groups" => [
+            "List of Lie groups" => "groups/index.md",
+            "General Linear" => "groups/general_linear.md",
+            "Translation group" => "groups/translation.md",
+        ],
         "Interfaces" => [
             "Lie group" => "interface/group.md",
             "Lie algebra" => "interface/algebra.md",
             "Group operation" => "interface/operations.md",
             "Group action" => "interface/actions.md",
         ],
-        "Lie groups" => [
-            "List of Lie Groups" => "groups/index.md",
-            "Translation group" => "groups/translation.md",
-        ],
         "Contributing to LieGroups.jl" => "contributing.md",
         "Notation" => "notation.md",
         "Changelog" => "news.md",

diff --git a/docs/src/groups/general_linear.md b/docs/src/groups/general_linear.md
@@ -0,0 +1,7 @@
+# The general linear group
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["groups/general_linear_group.jl"]
+Order = [:type, :function]
+```
diff --git a/docs/src/groups/index.md b/docs/src/groups/index.md
@@ -4,4 +4,5 @@
 
 | Group | Manifold | ``∘`` | Comment |
 |:------|:---------|:---------:|:------|
+| [`GeneralLinearGroup`](@ref) | [`InvertibleMatrices`](@extref `Manifolds.InvertibleMatrices`) | [`*`](@ref MatrixMultiplicationGroupOperation) | |
 | [`TranslationGroup`](@ref) | [`Euclidean`](@extref `Manifolds.Euclidean`) | [`+`](@ref AdditionGroupOperation) | |
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,3 +1,11 @@
 # LieGroups.jl
 
-Welcome to the Documentation of `LieGroups.jl`.
+Welcome to the Documentation of `LieGroups.jl`.
+
+```@meta
+CurrentModule = LieGroups
+```
+
+```@docs
+LieGroups.LieGroups
+```
diff --git a/docs/src/interface/algebra.md b/docs/src/interface/algebra.md
@@ -2,6 +2,7 @@
 
 ```@docs
 LieAlgebra
+LieAlgebraOrthogonalBasis
 ```
 
 ## Functions on Lie algebras

diff --git a/docs/src/interface/operations.md b/docs/src/interface/operations.md
@@ -17,6 +17,21 @@ The following sections collect these.
 
 ```@autodocs
 Modules = [LieGroups]
-Pages = ["addition.jl"]
+Pages = ["addition_operation.jl"]
 Order = [:type, :function]
+```
+
+## [Multiplication group operation](@id multiplication-operation-sec)
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["multiplication_operation.jl"]
+Order = [:type, :function]
+```
+
+## Literature
+
+```@bibliography
+Pages = ["operations.md"]
+Canonical=false
 ```
diff --git a/docs/src/notation.md b/docs/src/notation.md
@@ -3,7 +3,7 @@
 In this package,the notation introduced in [Manifolds.jl Notation](https://juliamanifolds.github.io/Manifolds.jl/latest/misc/notation.html) is used with the following additional parts.
 
 | Symbol | Description | Also used | Comment |
-|:--:|:--------------- |:--:|:-- |
+|:----:|:--------------- |:----:|:--- |
 | ``∘`` | a group operation | | |
 | ``c_g:\mathcal G → \mathcal G`` | the conjugation map (with `g`) | | |
 | ``\mathrm{e}`` | identity element of a group | | |

diff --git a/docs/src/references.bib b/docs/src/references.bib
@@ -3,6 +3,23 @@
 #
 # A
 
+#
+#
+# G
+@inproceedings{Giles:2008,
+    ADDRESS   = {Berlin, Heidelberg},
+    SERIES    = {Lecture {Notes} in {Computational} {Science} and {Engineering}},
+    TITLE     = {Collected {Matrix} {Derivative} {Results} for {Forward} and {Reverse} {Mode} {Algorithmic} {Differentiation}},
+    ISBN      = {978-3-540-68942-3},
+    DOI       = {10.1007/978-3-540-68942-3_4},
+    BOOKTITLE = {Advances in {Automatic} {Differentiation}},
+    PUBLISHER = {Springer},
+    AUTHOR    = {Giles, Mike B.},
+    EDITOR    = {Bischof, Christian H. and Bücker, H. Martin and Hovland, Paul and Naumann, Uwe and Utke, Jean},
+    YEAR      = {2008},
+    PAGES     = {35--44}
+}
+
 #
 #
 # H

diff --git a/docs/src/tutorials/getstarted.md b/docs/src/tutorials/getstarted.md
@@ -0,0 +1 @@
+# 🚀 Get Started with LieGroups.jl
diff --git a/docs/src/tutorials/transition.md b/docs/src/tutorials/transition.md
@@ -0,0 +1,52 @@
+# Transition from `GroupManifolds` in `Manifolds.jl`
+
+One predecessor of `LieGroups.jl` are the [`GroupManifold`](@extref `Manifolds.GroupManifold`)s 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`](@ref) 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.jl` | `LieGroups.jl` | Comment |
+|:---------- |:---------- |:-------------- |
+| `AdditionOperation` | [`AdditionGroupOperation`](@ref) | |
+| `LeftForwardAction` | [`LeftGroupOperation`](@ref)
+| `RightBackwardAction` | [`RightGroupOperation`](@ref) | |
+| `LeftBackwardAction` | [`InverseRightGroupOperation`](@ref) | note that this is now also aa [`AbstractLeftGroupActionType`](@ref) |
+| | [`LieAlgebra`](@ref)`(G)` | new alias to emphasize its manifold- and vector structure as well as for a few dispatch methods. |
+| `GroupManifold(M, op)` | [`LieGroup`](@ref)`(M, op)` | |
+| `RightForwardAction` | [`InverseLeftGroupOperation`](@ref) | note that this is an [`AbstractRightGroupActionType`](@ref) |
+| `adjoint` | [`adjoint`](@ref) | now implemented with a default, when you provide [`diff_conjugate!`](@ref).
+| `apply_diff` | [`diff_apply`](@ref) | modifiers (diff) come first, consistent with [`ManifoldsDiff.jl`](https://juliamanifolds.github.io/ManifoldDiff.jl/stable/) |
+| `apply_diff_group` | [`diff_group_apply`](@ref) | modifiers (diff/group) come first, consistent with [`ManifoldsDiff.jl`](https://juliamanifolds.github.io/ManifoldDiff.jl/stable/) |
+| | [`conjugate`](@ref), [`diff_conjugate`](@ref) | a new function to model ``c_g: \mathcal G → \mathcal G`` given by ``c_g(h) = g∘h∘g^{-1}`` |
+| `exp(G, g, X)` | `exp(`[`base_manifold`](@ref base_manifold(G::LieGroup))`(G), g, X)` | the previous defaults whenever not agreeing with the invariant one can now be accessed on the internal manifold |
+| `exp_inv(G, g, X)` | [`exp`](@ref exp(G::LieGroup, g, X, t::Number))`(G, g, X)`  | the exponential map invariant to the group operation is the default on Lie groups here |
+| `exp_lie(G, X)` | [`exp`](@ref exp(G::LieGroup, e::Identity, X, t::Number))`(G, `[`Identity`](@ref)`(G), X)` | the (matrix) exponential is now the one at the [`Identity`](@ref)`(G)`, since there it agrees with the invariant one |
+| `inverse_translate(G, g, h, c)` | [`inv_left_compose`](@ref)`(G, g, h)`, [`inv_right_compose`](@ref)`(G, g, h)` | compute ``g^{-1}∘h`` and ``g∘h^{-1}``, resp. |
+| `inverse_tranlsate_diff(G, g, h, X, LeftForwardAction())` | - | discontinued, use `diff_left_compose(G, inv(G,g), h)` |
+| `inverse_tranlsate_diff(G, g, h, X, RightBackwardAction())` | - | discontinued, use `diff_left_compose(G, h, inv(G,g))` |
+| `log(G, g, h)` | `log(`[`base_manifold`](@ref base_manifold(G::LieGroup))`(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`](@ref log(G::LieGroup, g, h))`(G, g, h)` | the logarithmic map invariant to the group operation is the default on Lie groups here |
+| `log_lie(G, g)` | [`log`](@ref log(G::LieGroup, e::Identity, g))`(G, `[`Identity`](@ref)`(G), g)` | the (matrix) logarithm is now the one at the identity, since there it agrees with the invariant one |
+| `switch_direction(A)` | [`inv`](@ref inv(::AbstractGroupAction))`(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`](@ref switch(::AbstractGroupAction))`(A)` | switches from a left action to its corresponding right action. |
+| `translate(G, g, h)` | [`compose`](@ref)`(G, g, h)` | unified to `compose` |
+| `translate_diff(G, g, X, c)` | [`diff_left_compose`](@ref)`(G, g, h, X)`, [`diff_right_compose`](@ref)`(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 |
+|`VeeOrthogonalBasis` | [`LieAlgebraOrthogonalBasis`](@ref) | |
+
+# Notable changes
+
+* The [`GeneralLinearGroup`](@ref) (formerly `GeneralLinear`) switched to using its Lie algebra to represent tangent vectors.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		ignore:
		- "src/documentation_glossary.jl" # exclude this since it is just use to create the docs and code cov goes bogus on this.