Extend support for SpecialEuclidean, fiber bundles, optionally static sizes

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        julia-version: ["1.6", "1.8", "~1.9.0-0"]
+        julia-version: ["1.6", "~1.9.0-0"]
         os: [ubuntu-latest, macOS-latest]
         group:
           - 'test_manifolds'

NEWS.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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.9.0] - 2023-mm-dd
+
+### Added
+
+- Vector bundles are generalized to fiber bundles. Old `BundleFibers` functionality was reworked to better match mathematical abstractions. Fiber bundle functionality is experimental and minor changes may happen without a breaking release, with the exception of `TangentBundle` which is considered to be stable.
+- `RotationTranslationAction` is introduced.
+
+### Changed
+
+- Sizes of all manifolds can now be either encoded in type or stored in a field to avoid over-specialization.
+  The default is set to store the size in type parameter (except for `PowerManifold` and its variants), replicating the previous behavior.
+  For field storage, pass the `parameter=:field` keyword argument to manifold constructor.
+  For example statically sized `CenteredMatrices{m,n}` is now `CenteredMatrices{TypeParameter{Tuple{m,n}}}`, whereas the type of special Euclidean group with field-stored size is `CenteredMatrices{Tuple{Int,Int}}`. Similar change applies to:
+  - `CenteredMatrices{m,n}`,
+  - `CholeskySpace{N}`,
+  - `Elliptope{N,K}`,
+  - `Euclidean`,
+  - `FixedRankMatrices{m,n,k}`,
+  - `KendallsPreShapeSpace{n,k}`,
+  - `KendallsShapeSpace{n,k}`,
+  - `GeneralLinear{n}`,
+  - `GeneralUnitaryMultiplicationGroup{n}`,
+  - `GeneralizedGrassmann{n,k}`,
+  - `GeneralizedStiefel{n,k}`,
+  - `Grassmann{n,k}`,
+  - `Heisenberg{n}`,
+  - `Hyperbolic{n}`,
+  - `MultinomialMatrices{N,M}`,
+  - `MultinomialDoublyStochastic{n}`,
+  - `MultinomialSymmetric{n}`,
+  - `Orthogonal{n}`,
+  - `PowerManifold`,
+  - `PositiveArrays`,
+  - `PositiveMatrices`,
+  - `PositiveNumbers`,
+  - `ProbabilitySimplex{n}`,
+  - `SPDFixedDeterminant{n}`,
+  - `SpecialLinear{n}`,
+  - `SpecialOrthogonal{n}`,
+  - `SpecialUnitary{n}`,
+  - `SpecialEuclidean{n}`,
+  - `SpecialEuclideanManifold{n}`,
+  - `Spectrahedron{n,k}`,
+  - `SphereSymmetricMatrices{N}`,
+  - `Stiefel{n,k}`,
+  - `SymmetricMatrices{N}`,
+  - `SymmetricPositiveDefinite{n}`,
+  - `SymmetricPositiveSemidefiniteFixedRank{n,k}`,
+  - `Symplectic{n}`,
+  - `SymplecticStiefel{n,k}`,
+  - `TranslationGroup`,
+  - `Tucker`.
+
+  For example
+
+  ```{julia}
+  function Base.show(io::IO, ::CenteredMatrices{m,n}) where {m,n}
+      return print(io, "CenteredMatrices($m, $n)")
+  end
+  ```
+
+  needs to be replaced with
+
+  ```{julia}
+  function Base.show(io::IO, ::CenteredMatrices{TypeParameter{Tuple{m,n}}}) where {m,n}
+      return print(io, "CenteredMatrices($m, $n)")
+  end
+  ```
+
+  for statically-sized groups and
+
+  ```{julia}
+  function Base.show(io::IO, M::CenteredMatrices{Tuple{Int,Int}})
+      m, n = get_parameter(M.size)
+      return print(io, "CenteredMatrices($m, $n; parameter=:field)")
+  end
+  ```
+
+  for groups with size stored in field. Alternatively, you can use a single generic method like this:
+
+  ```{julia}
+  function Base.show(io::IO, M::CenteredMatrices{T}) where {T}
+      m, n = get_parameter(M)
+      if T <: TypeParameter
+          return print(io, "CenteredMatrices($m, $n)")
+      else
+          return print(io, "CenteredMatrices($m, $n; parameter=:field)")
+      end
+  end
+  ```
+
+- Argument order for type aliases `RotationActionOnVector` and `RotationTranslationActionOnVector`: most often dispatched on argument is now first.
+- A more consistent handling of action direction was introduced. 4-valued `ActionDirection` was split into 2-valued `ActionDirection` (either left or right action) and `GroupActionSide` (action acting from the left or right side). See [https://github.com/JuliaManifolds/Manifolds.jl/issues/637](https://github.com/JuliaManifolds/Manifolds.jl/issues/637) for a design discussion.
+
+### Removed
+
+- `ProductRepr` is removed; please use `ArrayPartition` instead.
+- Default methods throwing "not implemented" `ErrorException` for some group-related operations. Standard `MethodError` is now thrown instead.
+- `LinearAffineMetric` was deprecated in a previous release and the symbol is now removed.
+  Please use `AffineInvariantMetric` instead.

Project.toml

@@ -1,7 +1,7 @@
 name = "Manifolds"
 uuid = "1cead3c2-87b3-11e9-0ccd-23c62b72b94e"
 authors = ["Seth Axen <[email protected]>", "Mateusz Baran <[email protected]>", "Ronny Bergmann <[email protected]>", "Antoine Levitt <[email protected]>"]
-version = "0.8.81"
+version = "0.9.0"
 
 [deps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
@@ -49,8 +49,8 @@ Einsum = "0.4"
 Graphs = "1.4"
 HybridArrays = "0.4"
 Kronecker = "0.4, 0.5"
-ManifoldDiff = "0.3.6"
-ManifoldsBase = "0.14.12"
+ManifoldDiff = "0.3.7"
+ManifoldsBase = "0.15.0"
 MatrixEquations = "2.2"
 OrdinaryDiffEq = "6.31"
 Plots = "1"

benchmark/benchmarks.jl

@@ -141,7 +141,7 @@ function add_manifold_benchmarks()
         inverse_retraction_methods=inverse_retraction_methods_rot,
     )
 
-    pts_prod_mpoints = [Manifolds.ProductRepr(p[1], p[2]) for p in zip(pts_s2, pts_r2)]
+    pts_prod_mpoints = [ArrayPartition(p[1], p[2]) for p in zip(pts_s2, pts_r2)]
     add_manifold(
         m_prod,
         pts_prod_mpoints,
@@ -155,14 +155,14 @@ function add_manifold_benchmarks()
         TB = TangentBundle(s2)
 
         pts_tb = [
-            ProductRepr(convert(T, [1.0, 0.0, 0.0]), convert(T, [0.0, -1.0, -1.0])),
-            ProductRepr(convert(T, [0.0, 1.0, 0.0]), convert(T, [2.0, 0.0, 1.0])),
-            ProductRepr(convert(T, [1.0, 0.0, 0.0]), convert(T, [0.0, 2.0, -1.0])),
+            ArrayPartition(convert(T, [1.0, 0.0, 0.0]), convert(T, [0.0, -1.0, -1.0])),
+            ArrayPartition(convert(T, [0.0, 1.0, 0.0]), convert(T, [2.0, 0.0, 1.0])),
+            ArrayPartition(convert(T, [1.0, 0.0, 0.0]), convert(T, [0.0, 2.0, -1.0])),
         ]
         add_manifold(
             TB,
             pts_tb,
-            "Tangent bundle of S² using MVectors, ProductRepr";
+            "Tangent bundle of S² using MVectors, ArrayPartition";
             test_tangent_vector_broadcasting=false,
         )
     end
@@ -203,13 +203,11 @@ function add_manifold_benchmarks()
         sphere_tv_dist =
             Manifolds.normal_tvector_distribution(Ms, (@MVector [1.0, 0.0, 0.0]), 1.0)
         power_s1_tv_dist = Manifolds.PowerFVectorDistribution(
-            TangentBundleFibers(Ms1),
-            rand(power_s1_pt_dist),
+            TangentSpace(Ms1, rand(power_s1_pt_dist)),
             sphere_tv_dist,
         )
         power_s2_tv_dist = Manifolds.PowerFVectorDistribution(
-            TangentBundleFibers(Ms2),
-            rand(power_s2_pt_dist),
+            TangentSpace(Ms2, rand(power_s2_pt_dist)),
             sphere_tv_dist,
         )
 
@@ -224,13 +222,11 @@ function add_manifold_benchmarks()
         )
         rotations_tv_dist = Manifolds.normal_tvector_distribution(Mr, MMatrix(id_rot), 1.0)
         power_r1_tv_dist = Manifolds.PowerFVectorDistribution(
-            TangentBundleFibers(Mr1),
-            rand(power_r1_pt_dist),
+            TangentSpace(Mr1, rand(power_r1_pt_dist)),
             rotations_tv_dist,
         )
         power_r2_tv_dist = Manifolds.PowerFVectorDistribution(
-            TangentBundleFibers(Mr2),
-            rand(power_r2_pt_dist),
+            TangentSpace(Mr2, rand(power_r2_pt_dist)),
             rotations_tv_dist,
         )
 

docs/Project.toml

@@ -30,7 +30,7 @@ FiniteDifferences = "0.12"
 Graphs = "1.4"
 HybridArrays = "0.4"
 IJulia = "1"
-ManifoldsBase = "0.14.1"
+ManifoldsBase = "0.15.0"
 OrdinaryDiffEq = "6"
 Plots = "1"
 PythonPlot = "1"

docs/make.jl

@@ -41,23 +41,25 @@ using OrdinaryDiffEq, BoundaryValueDiffEq, DiffEqCallbacks
 using Test, FiniteDifferences
 ENV["GKSwstype"] = "100"
 
-# (d) add contributing.md to docs
+# (d) add CONTRIBUTING.md and NEWS.md to docs
 generated_path = joinpath(@__DIR__, "src", "misc")
 base_url = "https://github.com/JuliaManifolds/Manifolds.jl/blob/master/"
 isdir(generated_path) || mkdir(generated_path)
-open(joinpath(generated_path, "contributing.md"), "w") do io
-    # Point to source license file
-    println(
-        io,
-        """
-        ```@meta
-        EditURL = "$(base_url)CONTRIBUTING.md"
-        ```
-        """,
-    )
-    # Write the contents out below the meta block
-    for line in eachline(joinpath(dirname(@__DIR__), "CONTRIBUTING.md"))
-        println(io, line)
+for fname in ["CONTRIBUTING.md", "NEWS.md"]
+    open(joinpath(generated_path, fname), "w") do io
+        # Point to source license file
+        println(
+            io,
+            """
+            ```@meta
+            EditURL = "$(base_url)$(fname)"
+            ```
+            """,
+        )
+        # Write the contents out below the meta block
+        for line in eachline(joinpath(dirname(@__DIR__), fname))
+            println(io, line)
+        end
     end
 end
 
@@ -138,6 +140,7 @@ makedocs(;
                 "Unit-norm symmetric matrices" => "manifolds/spheresymmetricmatrices.md",
             ],
             "Combined manifolds" => [
+                "Fiber bundle" => "manifolds/fiber_bundle.md",
                 "Graph manifold" => "manifolds/graph.md",
                 "Power manifold" => "manifolds/power.md",
                 "Product manifold" => "manifolds/product.md",
@@ -154,14 +157,16 @@ makedocs(;
             "Atlases and charts" => "features/atlases.md",
             "Differentiation" => "features/differentiation.md",
             "Distributions" => "features/distributions.md",
+            "Group actions" => "features/group_actions.md",
             "Integration" => "features/integration.md",
             "Statistics" => "features/statistics.md",
             "Testing" => "features/testing.md",
             "Utilities" => "features/utilities.md",
         ],
         "Miscellanea" => [
             "About" => "misc/about.md",
-            "Contributing" => "misc/contributing.md",
+            "Changelog" => "misc/NEWS.md",
+            "Contributing" => "misc/CONTRIBUTING.md",
             "Internals" => "misc/internals.md",
             "Notation" => "misc/notation.md",
             "References" => "misc/references.md",

docs/src/features/group_actions.md

@@ -0,0 +1,63 @@
+# Group actions
+
+Group actions represent actions of a given group on a specified manifold.
+The following operations are available:
+
+* [`action_side`](@ref): whether action acts from the [`LeftSide`](@ref) or [`RightSide`](@ref) (not to be confused with action direction).
+* [`apply`](@ref): performs given action of an element of the group on an object of compatible type.
+* [`apply_diff`](@ref): differential of [`apply`](@ref) with respect to the object it acts upon.
+* [`direction`](@ref): tells whether a given action is [`LeftAction`](@ref), [`RightAction`](@ref).
+* [`inverse_apply`](@ref): performs given action of the inverse of an element of the group on an object of compatible type. By default inverts the element and calls [`apply`](@ref) but it may be have a faster implementation for some actions.
+* [`inverse_apply_diff`](@ref): counterpart of [`apply_diff`](@ref) for [`inverse_apply`](@ref).
+* [`optimal_alignment`](@ref): determine the element of a group that, when it acts upon a point, produces the element closest to another given point in the metric of the G-manifold.
+
+Furthermore, group operation action features the following:
+
+* [`translate`](@ref Main.Manifolds.translate): an operation that performs either ([`LeftAction`](@ref)) on the [`LeftSide`](@ref) or ([`RightAction`](@ref)) on the [`RightSide`](@ref) translation, or actions by inverses of elements ([`RightAction`](@ref) on the [`LeftSide`](@ref) and [`LeftAction`](@ref) on the [`RightSide`](@ref)). This is by default performed by calling [`compose`](@ref) with appropriate order of arguments. This function is separated from `compose` mostly to easily represent its differential, [`translate_diff`](@ref).
+* [`translate_diff`](@ref): differential of [`translate`](@ref Main.Manifolds.translate) with respect to the point being translated.
+* [`adjoint_action`](@ref): adjoint action of a given element of a Lie group on an element of its Lie algebra.
+* [`lie_bracket`](@ref): Lie bracket of two vectors from a Lie algebra corresponding to a given group.
+
+The following group actions are available:
+
+* Group operation action [`GroupOperationAction`](@ref) that describes action of a group on itself.
+* [`RotationAction`](@ref), that is action of [`SpecialOrthogonal`](@ref) group on different manifolds.
+* [`TranslationAction`](@ref), which is the action of [`TranslationGroup`](@ref) group on different manifolds.
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["groups/group_action.jl"]
+Order = [:type, :function]
+```
+
+## Group operation action
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["groups/group_operation_action.jl"]
+Order = [:type, :function]
+```
+
+## Rotation action
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["groups/rotation_action.jl"]
+Order = [:type, :function]
+```
+
+## Translation action
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["groups/translation_action.jl"]
+Order = [:type, :function]
+```
+
+## Rotation-translation action (special Euclidean)
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["groups/rotation_translation_action.jl"]
+Order = [:type, :const, :function]
+```

docs/src/features/utilities.md

@@ -1,13 +1,14 @@
-# Ease of notation
+# Utilities
+
+## Ease of notation
 
 The following terms introduce a nicer notation for some operations, for example using the ∈ operator, $p ∈ \mathcal M$, to determine whether $p$ is a point on the [`AbstractManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#ManifoldsBase.AbstractManifold)  $\mathcal M$.
 
 ````@docs
 in
-TangentSpace
 ````
 
-# Fallback for the exponential map: Solving the corresponding ODE
+## Fallback for the exponential map: Solving the corresponding ODE
 
 When additionally loading [`NLSolve.jl`](https://github.com/JuliaNLSolvers/NLsolve.jl) the following fallback for the exponential map is available.
 
@@ -17,17 +18,9 @@ Pages = ["nlsolve.jl"]
 Order = [:type, :function]
 ```
 
-# Public documentation
-
-The following functions are of interest for extending and using the [`ProductManifold`](@ref).
-
-```@docs
-submanifold_component
-submanifold_components
-ProductRepr
-```
+## Public documentation
 
-## Specific exception types
+### Specific exception types
 
 For some manifolds it is useful to keep an extra index, at which point on the manifold, the error occurred as well as to collect all errors that occurred on a manifold. This page contains the manifold-specific error messages this package introduces.
 

docs/src/manifolds/fiber_bundle.md

@@ -0,0 +1,17 @@
+# [Fiber bundles](@id FiberBundleSection)
+
+Fiber bundle $E$ is a manifold that is built on top of another manifold $\mathcal M$ (base space).
+It is characterized by a continuous function $Π : E → \mathcal M$. For each point $p ∈ \mathcal M$ the preimage of $p$ by $Π$, $Π^{-1}(\{p\})$ is called a fiber $F$.
+Bundle projection can be performed using function [`bundle_projection`](@ref).
+
+`Manifolds.jl` primarily deals with the case of trivial bundles, where $E$ can be identified with a product $M \times F$.
+
+[Vector bundles](@ref VectorBundleSection) is a special case of a fiber bundle. Other examples include unit tangent bundle. Note that in general fiber bundles don't have a canonical Riemannian structure but can at least be equipped with an [Ehresmann connection](https://en.wikipedia.org/wiki/Ehresmann_connection), providing notions of parallel transport and curvature.
+
+## Documentation
+
+```@autodocs
+Modules = [Manifolds, ManifoldsBase]
+Pages = ["manifolds/Fiber.jl", "manifolds/FiberBundle.jl"]
+Order = [:constant, :type, :function]
+```