(Special) Orthogonal / Unitary / Euclidean groups (#17)

* Initial commit.
* Start SE(n).
* start (S)U(n)
* start (S)O(n)
* implement a generic semidirect product Lie group
---------

Co-authored-by: Mateusz Baran <[email protected]>

NEWS.md

@@ -14,6 +14,14 @@ Everything denoted by “formerly” refers to the previous name in [`Manifolds.
 * `LieAlgebra`
 * `LieGroup` (formerly `GroupManifold`) as well as the concrete groups
   * `TranslationGroup`
+  * `SpecialEuclideanGroup` (formerly `SpecialEuclidean`) including
+    * `SpecialEuclideanMatrixPoint` and `SpecialEuclideanMatrixTangentVector` when representing thepoints as affine (abstract) matrices
+    * `SpecialEuclideanProductPoint` and `SpecialEuclideanProductTangentVector` when representing them in a product structure, e.g. as an `ArrayPartition` from [`RecursiveArrayTools`](https://github.com/SciML/RecursiveArrayTools.jl).
+    * neither of those types is necessary, besides for conversion between both. The product representation differs for the left and right semidirect product, while the affine matrix variant does not.
+  * `SpecialOrthogonalGroup` (formerly `SpecialOrthogonal`)
+  * `SpecialUnitaryGroup` (formerly `SpecialUnitary`)
+  * `OrthogonalGroup` (formerly `Orthogonal`)
+  * `UnitaryGroup` (formerly `Unitary`)
   * `GeneralLinearGroup` (formerly `GeneralLinear`)
   * `HeisenbergGroup`
   * `LeftSemidirectProductLieGroup` (formerly `SemidirectProductGroup`)
@@ -25,7 +33,7 @@ Everything denoted by “formerly” refers to the previous name in [`Manifolds.
   * `⋊` (alias for `RightSemidirectProductGroupOperation` when a `default_right_action(G,H)` is defined for the two groups)
 * `AbstractGroupOperation` as well as its concrete subtypes
   * `AdditionGroupOperation` (formerly `AdditionOperation`)
-  * `MultiplicationGroupOperation` (formerly `MultiplicationOperation`)
+  * `MatrixMultiplicationGroupOperation` (formerly `MultiplicationOperation`)
   * `PowerGroupOperation` (formerly the Lie group was stored inside a power manifold)
   * `ProductGroupOperation` (formerly the Lie groups were stored inside a product manifold)
   * `LeftSemidirectProductGroupOperation` (this was formerly only implicitly stored in the `SemidirectProductGroup`)
@@ -38,7 +46,8 @@ Everything denoted by “formerly” refers to the previous name in [`Manifolds.
   * `RightGroupOperationAction` (formerly `RightBackwardAction`)
   * `InverseLeftGroupOperationAction` (formerly `RightForwardAction`)
   * `InverseRightGroupOperationAction` (formerly `LeftBackwardAction`)
-* `LieAlgebraOrthogonalBasis` (replaces `VeeOrthogonalBasis`, which is still available in `ManifoldsBase.jl`)
+* `DefaultLieAlgebraOrthogonalBasis` (replaces `VeeOrthogonalBasis`, which is still available in `ManifoldsBase.jl`)
+* `AbstractLieGroupPoint` and `AbstractLieAlgebraTangentVector` as abstract types to introduce point and Lie algebra tangent vector representations
 * `Identity`
 * `apply`and `apply!`
 * `base_manifold` to access the manifold within a Lie group
@@ -48,13 +57,14 @@ Everything denoted by “formerly” refers to the previous name in [`Manifolds.
 * `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!`)
+* `exp(G::LieGroup, X)` and `exp!(G::LieGroup, h, X)` (formerly `exp_lie` and `exp_lie!`)
 * `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!`
+* `jacobian_conjugate` (formerly `adjoint_matrix`, which is now a special case of this)
 * `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`)
@@ -64,7 +74,16 @@ 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
 * all `inverse_apply` functions are not implemented here, since it is recommended to use `apply(inv(A), g, p)` as a replacement.
 
-## Old Changelog pre 0.1.0
+## [0.0.3] – unreleased
+
+
+### Added
+
+* Finishes most of the work on the interface for the `LieGroup` type and the new `LieAlgebra` type.
+* Finishes a generic implementation of a `SemiDirectProductGroupOperation`
+* All details will be detailed in the next release
+
+## Old Changelog pre 0.0.3
 
 __Two previous releases where done by Yueh-Hua Tu in 2022 before he was so kind to transfer the development to the JuliaManifolds GitHub organisation.__
 

Project.toml

@@ -1,21 +1,29 @@
 name = "LieGroups"
 uuid = "6774de46-80ba-43f8-ba42-e41071ccfc5f"
 authors = ["Seth Axen <[email protected]>", "Mateusz Baran <[email protected]>", "Ronny Bergmann <[email protected]>", "Yueh-Hua Tu", "Olivier Verdier <[email protected]>"]
-version = "0.1.0"
+version = "0.0.3"
 
 [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"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+
+[weakdeps]
+RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
+
+[extensions]
+LieGroupsRecursiveArrayToolsExt = "RecursiveArrayTools"
 
 [compat]
 Aqua = "0.8"
 LinearAlgebra = "1.10"
-Manifolds = "0.10.11"
-ManifoldsBase = "0.15.20"
+Manifolds = "0.10.13"
+ManifoldsBase = "1"
 Random = "1.10"
 RecursiveArrayTools = "2, 3"
+StaticArrays = "1.5"
 Test = "1.10"
 julia = "1.10"
 

docs/make.jl

@@ -21,8 +21,7 @@ Arguments
   If they are generated once they are cached accordingly.
   Then you can spare time in the rendering by not passing this argument.
   If quarto is not run, some tutorials are generated as empty files, since they
-  are referenced from within the documentation. These are currently
-  `Optimize.md` and `ImplementOwnManifold.md`.
+  are referenced from within the documentation. This is currently `getstarted.md`.
 """,
     )
     exit(0)
@@ -34,6 +33,7 @@ end
 if Base.active_project() != joinpath(@__DIR__, "Project.toml")
     using Pkg
     Pkg.activate(@__DIR__)
+    # local temp hack - load ManifoldsBase and Manifold in dev as well
     Pkg.develop(PackageSpec(; path=(@__DIR__) * "/../"))
     Pkg.resolve()
     Pkg.instantiate()
@@ -56,7 +56,8 @@ if "--quarto" ∈ ARGS
         run(`quarto render $(tutorials_folder)`)
         return nothing
     end
-else # fallback to at least create empty files for Optimize and Implement
+else
+    # fallback to at least create empty files for tutorials that are directly linked from the docs
     #    touch(joinpath(@__DIR__, "src/tutorials/Optimize.md"))
 end
 
@@ -113,7 +114,7 @@ links = InterLinks(
 makedocs(;
     format=Documenter.HTML(;
         prettyurls=(get(ENV, "CI", nothing) == "true") || ("--prettyurls" ∈ ARGS),
-        assets=["assets/favicon.ico", "assets/citations.css"],
+        assets=["assets/favicon.ico", "assets/citations.css", "assets/link-icons.css"],
     ),
     modules=[LieGroups],
     authors="Seth Axen, Mateusz Baran, Ronny Bergmann, Olivier Verdier, and contributors",
@@ -126,10 +127,15 @@ makedocs(;
             "List of Lie groups" => "groups/index.md",
             "General Linear" => "groups/general_linear.md",
             "Heisenberg" => "groups/heisenberg_group.md",
+            "Orthogonal group" => "groups/orthogonal_group.md",
             "Power group" => "groups/power_group.md",
             "Product group" => "groups/product_group.md",
             "Semidirect product group" => "groups/semidirect_product_group.md",
-            "Translation group" => "groups/translation.md",
+            "Special Euclidean group" => "groups/special_euclidean_group.md",
+            "Special orthogonal group" => "groups/special_orthogonal_group.md",
+            "Special unitary group" => "groups/special_unitary_group.md",
+            "Translation group" => "groups/translation_group.md",
+            "Unitary group" => "groups/unitary_group.md",
         ],
         "Interfaces" => [
             "Lie group" => "interface/group.md",

docs/src/assets/link-icons.css

@@ -0,0 +1,56 @@
+a[href^="https://juliamanifolds.github.io/ManifoldsBase.jl/"]::before {
+    content: "";
+    background-image: url('logo-manifoldsbase.png');
+    background-size: contain;
+    background-repeat: no-repeat;
+    display: inline-block;
+    height: 1em;
+    width: 1em;
+    margin-right: 4px;
+    vertical-align: middle;
+}
+
+a[href^="https://juliamanifolds.github.io/Manifolds.jl/"]::before {
+    content: "";
+    background-image: url('logo-manifolds.png');
+    background-size: contain;
+    background-repeat: no-repeat;
+    display: inline-block;
+    height: 1em;
+    width: 1em;
+    margin-right: 4px;
+    vertical-align: middle;
+}
+
+a[href^="https://manoptjl.org/"]::before {
+    content: "";
+    background-image: url('logo-manopt.png');
+    background-size: contain;
+    background-repeat: no-repeat;
+    display: inline-block;
+    height: 1em;
+    width: 1em;
+    margin-right: 4px;
+    vertical-align: middle;
+}
+
+a[href^="https://en.wikipedia.org/"]::before {
+    content: "";
+    background-image: url('wikipedia.png');
+    background-size: contain;
+    background-repeat: no-repeat;
+    display: inline-block;
+    height: 1em;
+    width: 1em;
+    margin-right: 4px;
+    vertical-align: middle;
+}
+
+@media (prefers-color-scheme: dark) {
+    a[href^="https://juliamanifolds.github.io/ManifoldsBase.jl/"]::before {
+        background-image: url('logo-manifoldsbase-dark.png');
+    }
+    a[href^="https://juliamanifolds.github.io/Manifolds.jl/"]::before {
+        background-image: url('logo-manifolds-dark.png');
+    }
+}

docs/src/groups/heisenberg_group.md

@@ -5,3 +5,10 @@ Modules = [LieGroups]
 Pages = ["groups/heisenberg_group.jl"]
 Order = [:type, :function]
 ```
+
+## Literature
+
+```@bibliography
+Pages = ["heisenberg_group.md"]
+Canonical=false
+```

docs/src/groups/index.md

@@ -5,4 +5,10 @@
 | Group | Manifold | ``∘`` | Comment |
 |:------|:---------|:---------:|:------|
 | [`GeneralLinearGroup`](@ref) | [`InvertibleMatrices`](@extref `Manifolds.InvertibleMatrices`) | [`*`](@ref MatrixMultiplicationGroupOperation) | |
-| [`TranslationGroup`](@ref) | [`Euclidean`](@extref `Manifolds.Euclidean`) | [`+`](@ref AdditionGroupOperation) | |
+| [`HeisenbergGroup`](@ref) | [`HeisenbergMatrices`](@extref `Manifolds.HeisenbergMatrices`) | [`*`](@ref MatrixMultiplicationGroupOperation) | |
+| [`OrthogonalGroup`](@ref) | [`OrthogonalMatrices`](@extref `Manifolds.OrthogonalMatrices`) | [`*`](@ref MatrixMultiplicationGroupOperation) | This can be interpreted as all rotations and reflections. |
+| [`SpecialEuclideanGroup`](@ref) | [`Rotations`](@extref `Manifolds.Rotations`)[`⋉`](@ref LeftSemidirectProductGroupOperation)[`Euclidean`](@extref `Manifolds.Rotations`) | [`∘`](@ref LeftSemidirectProductGroupOperation) | Analogously you can also use a [`⋊`](@ref RightSemidirectProductGroupOperation) if you prefer tuples `(t,R)` having the rotation matrix in the second component |
+| [`SpecialOrthogonalGroup`](@ref) | [`Rotations`](@extref `Manifolds.Rotations`) | [`*`](@ref MatrixMultiplicationGroupOperation) | |
+| [`SpecialUnitaryGroup`](@ref) | [`GeneralUnitaryMatrices`](@extref `Manifolds.GeneralUnitaryMatrices`) | [`*`](@ref MatrixMultiplicationGroupOperation) | |
+| [`TranslationGroup`](@ref) | [`Euclidean`](@extref `Manifolds.Euclidean`) | [`+`](@ref AdditionGroupOperation) | |
+| [`UnitaryGroup`](@ref) | [`UnitaryMatrices`](@extref `Manifolds.UnitaryMatrices`) | [`*`](@ref MatrixMultiplicationGroupOperation) | |

docs/src/groups/orthogonal_group.md

@@ -0,0 +1,24 @@
+# The orthogonal group
+
+```@docs
+OrthogonalGroup
+```
+
+For this Lie group, several implementations are already covered by the defaults in [the generic (matrix) multiplication operation](@ref multiplication-operation-sec).
+
+# Functions
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["groups/orthogonal_group.jl"]
+Order = [:function]
+```
+
+# Utility functions
+
+```@docs
+LieGroups.angles_4d_skew_sym_matrix
+LieGroups.cos_angles_4d_rotation_matrix
+LieGroups.log_safe!
+LieGroups.usinc_from_cos
+```

docs/src/groups/power_group.md

@@ -4,4 +4,6 @@
 Modules = [LieGroups]
 Pages = ["groups/power_group.jl"]
 Order = [:type, :function]
-```
+```
+
+On power Lie groups, all functions work element-wise, so for their formulae, check the corresponding single Lie group for details.

docs/src/groups/special_euclidean_group.md

@@ -0,0 +1,22 @@
+# The special Euclidean group
+
+```@docs
+SpecialEuclideanGroup
+```
+
+# Representation of points and tangent vectors
+
+```@docs
+SpecialEuclideanMatrixPoint
+SpecialEuclideanMatrixTangentVector
+SpecialEuclideanProductPoint
+SpecialEuclideanProductTangentVector
+```
+
+# Specific functions
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["groups/special_euclidean_group.jl"]
+Order = [:function]
+```

docs/src/groups/special_orthogonal_group.md

@@ -0,0 +1,15 @@
+# The special orthogonal group
+
+```@docs
+SpecialOrthogonalGroup
+```
+
+For this Lie group, several implementations are already covered by the defaults in [the generic (matrix) multiplication operation](@ref multiplication-operation-sec).
+
+# Functions
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["groups/special_orthogonal_group.jl"]
+Order = [:function]
+```

docs/src/groups/special_unitary_group.md

@@ -0,0 +1,7 @@
+# The special unitary group
+
+```@docs
+SpecialUnitaryGroup
+```
+
+For this Lie group, several implementations are already covered by the defaults in [the generic (matrix) multiplication operation](@ref multiplication-operation-sec).

docs/src/groups/unitary_group.md

@@ -0,0 +1,19 @@
+# The unitary group
+
+```@docs
+UnitaryGroup
+```
+
+For this Lie group, several implementations are already covered by the defaults in [the generic (matrix) multiplication operation](@ref multiplication-operation-sec). Besides that the following methods are implemented:
+
+```@autodocs
+Modules = [LieGroups]
+Pages = ["groups/unitary.jl"]
+Order = [:function]
+```
+
+# Utility functions and constants
+
+```@docs
+LieGroups.CommonUnitarySubGroup
+```

docs/src/interface/algebra.md

@@ -2,7 +2,7 @@
 
 ```@docs
 LieAlgebra
-LieAlgebraOrthogonalBasis
+DefaultLieAlgebraOrthogonalBasis
 ```
 
 ## Functions on Lie algebras
@@ -13,9 +13,15 @@ Pages = ["src/Lie_algebra/Lie_algebra_interface.jl"]
 Order = [:function]
 ```
 
+## Internal functions and macros
+
+```@docs
+LieGroups.@default_lie_algebra_fallbacks
+```
+
 ## Literature
 
 ```@bibliography
-Pages = ["group.md"]
+Pages = ["algebra.md"]
 Canonical=false
 ```

docs/src/interface/group.md

@@ -2,6 +2,8 @@
 
 ```@docs
 LieGroup
+AbstractLieAlgebraTangentVector
+AbstractLieGroupPoint
 ```
 
 ## Functions on Lie groups
@@ -12,6 +14,13 @@ Pages = ["src/interface.jl"]
 Order = [:function]
 ```
 
+## Internal functions and macros
+
+```@docs
+LieGroups.CommonUnitarySubAlgebra
+LieGroups.@default_lie_group_fallbacks
+```
+
 ## Literature
 
 ```@bibliography