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.

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/make.jl

@@ -138,6 +138,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",

docs/src/features/utilities.md

@@ -24,7 +24,6 @@ The following functions are of interest for extending and using the [`ProductMan
 ```@docs
 submanifold_component
 submanifold_components
-ProductRepr
 ```
 
 ## Specific exception types

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]
+```

docs/src/manifolds/group.md

@@ -185,16 +185,17 @@ Order = [:constant, :type, :function]
 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 [`LeftForwardAction`](@ref), [`RightForwardAction`](@ref), [`LeftBackwardAction`](@ref) or [`RightBackwardAction`](@ref).
+* [`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 left ([`LeftForwardAction`](@ref)) or right ([`RightBackwardAction`](@ref)) translation, or actions by inverses of elements ([`RightForwardAction`](@ref) and [`LeftBackwardAction`](@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`](@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.
@@ -235,6 +236,14 @@ Pages = ["groups/translation_action.jl"]
 Order = [:type, :function]
 ```
 
+### Rotation-translation action (special Euclidean)
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["groups/rotation_translation_action.jl"]
+Order = [:type, :function]
+```
+
 ## Metrics on groups
 
 Lie groups by default typically forward all metric-related operations like exponential or logarithmic map to the underlying manifold, for example [`SpecialOrthogonal`](@ref) uses methods for [`Rotations`](@ref) (which is, incidentally, bi-invariant), or [`SpecialEuclidean`](@ref) uses product metric of the translation and rotation parts (which is not invariant under group operation).

docs/src/manifolds/power.md

@@ -98,8 +98,8 @@ N = 5
 GN = PowerManifold(G, NestedReplacingPowerRepresentation(), N)
 
 q = [1.0 0.0; 0.0 1.0]
-p1 = [ProductRepr(SVector{2,Float64}([i - 0.1, -i]), SMatrix{2,2,Float64}(exp(R2, q, hat(R2, q, i)))) for i in 1:N]
-p2 = [ProductRepr(SVector{2,Float64}([i - 0.1, -i]), SMatrix{2,2,Float64}(exp(R2, q, hat(R2, q, -i)))) for i in 1:N]
+p1 = [ArrayPartition(SVector{2,Float64}([i - 0.1, -i]), SMatrix{2,2,Float64}(exp(R2, q, hat(R2, q, i)))) for i in 1:N]
+p2 = [ArrayPartition(SVector{2,Float64}([i - 0.1, -i]), SMatrix{2,2,Float64}(exp(R2, q, hat(R2, q, -i)))) for i in 1:N]
 
 X = similar(p1);
 

docs/src/manifolds/product.md

@@ -1,7 +1,7 @@
 # [Product manifold](@id ProductManifoldSection)
 
 Product manifold $\mathcal M = \mathcal{M}_1 × \mathcal{M}_2 × … × \mathcal{M}_n$ of manifolds $\mathcal{M}_1, \mathcal{M}_2, …, \mathcal{M}_n$.
-Points on the product manifold can be constructed using [`ProductRepr`](@ref) with canonical projections $Π_i : \mathcal{M} → \mathcal{M}_i$ for $i ∈ 1, 2, …, n$ provided by [`submanifold_component`](@ref).
+Points on the product manifold can be constructed using `ArrayPartition` (from `RecursiveArrayTools.jl`) with canonical projections $Π_i : \mathcal{M} → \mathcal{M}_i$ for $i ∈ 1, 2, …, n$ provided by [`submanifold_component`](@ref).
 
 ```@autodocs
 Modules = [Manifolds]

docs/src/manifolds/sphere.md

@@ -11,7 +11,7 @@ Sphere
 ```
 
 For the higher-dimensional arrays, for example unit (Frobenius) norm matrices, the manifold is generated using the size of the matrix.
-To create the unit sphere of $3×2$ real-valued matrices, write `ArraySphere(3,2)` and the complex case is done – as for the [`Euclidean`](@ref) case – with an keyword argument `ArraySphere(3,2; field = ℂ)`. This case also covers the classical sphere as a special case, but you specify the size of the vectors/embedding instead: The 2-sphere can here be generated `ArraySphere(3)`.
+To create the unit sphere of $3×2$ real-valued matrices, write `ArraySphere(3,2)` and the complex case is done – as for the [`Euclidean`](@ref) case – with an keyword argument `ArraySphere(3,2; field=ℂ)`. This case also covers the classical sphere as a special case, but you specify the size of the vectors/embedding instead: The 2-sphere can here be generated `ArraySphere(3)`.
 
 ```@docs
 ArraySphere

docs/src/manifolds/vector_bundle.md

@@ -1,19 +1,12 @@
 # [Vector bundles](@id VectorBundleSection)
 
-Vector 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$, such that for each point $p ∈ \mathcal M$ the preimage of $p$ by $Π$, $Π^{-1}(\{p\})$, has a structure of a vector space.
-These vector spaces are called fibers.
-Bundle projection can be performed using function [`bundle_projection`](@ref).
+Vector bundle $E$ is a special case of a [fiber bundle](@ref FiberBundleSection) where each fiber is a vector space.
 
-Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point $x$.
+Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point $p$.
 An object representing a tangent bundle can be obtained using the constructor called `TangentBundle`.
 
-Fibers of a vector bundle are represented by the type `VectorBundleFibers`.
-The important difference between functions operating on `VectorBundle` and `VectorBundleFibers` is that in the first case both a point on the underlying manifold and the vector are represented together (by a single argument) while in the second case only the vector part is present, while the point is supplied in a different argument where needed.
-
-`VectorBundleFibers` refers to the whole set of fibers of a vector bundle.
-There is also another type, [`VectorSpaceAtPoint`](@ref), that represents a specific fiber at a given point.
-This distinction is made to reduce the need to repeatedly construct objects of type [`VectorSpaceAtPoint`](@ref) in certain usage scenarios.
+There is also another type, [`VectorSpaceFiber`](@ref), that represents a specific fiber at a given point.
+This distinction is made to reduce the need to repeatedly construct objects of type [`VectorSpaceFiber`](@ref) in certain usage scenarios.
 This is also considered a manifold.
 
 ## FVector
@@ -25,7 +18,7 @@ It is used for example in musical isomorphisms (the [`flat`](@ref) and [`sharp`]
 
 ```@autodocs
 Modules = [Manifolds, ManifoldsBase]
-Pages = ["manifolds/VectorBundle.jl"]
+Pages = ["manifolds/VectorFiber.jl", "manifolds/VectorBundle.jl"]
 Order = [:constant, :type, :function]
 ```
 
@@ -37,8 +30,8 @@ The following code defines a point on the tangent bundle of the sphere $S^2$ and
 using Manifolds
 M = Sphere(2)
 TB = TangentBundle(M)
-p = ProductRepr([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])
-X = ProductRepr([0.0, 1.0, 0.0], [0.0, 0.0, -2.0])
+p = ArrayPartition([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])
+X = ArrayPartition([0.0, 1.0, 0.0], [0.0, 0.0, -2.0])
 ```
 
 An approximation of the exponential in the Sasaki metric using 1000 steps can be calculated as follows.

docs/src/misc/notation.md

@@ -22,7 +22,7 @@ Within the documented functions, the utf8 symbols are used whenever possible, as
 | ``n`` | dimension (of a manifold) | ``n_1,n_2,\ldots,m, \dim(\mathcal M)``| for the real dimension sometimes also ``\dim_{\mathbb R}(\mathcal M)``|
 | ``d(\cdot,\cdot)`` | (Riemannian) distance | ``d_{\mathcal M}(\cdot,\cdot)`` | |
 | ``\exp_p X`` | exponential map at ``p \in \mathcal M`` of a vector ``X \in T_p \mathcal M`` | ``\exp_p(X)`` | |
-| ``F`` | a fiber | | see [`VectorBundleFibers`](@ref) |
+| ``F`` | a fiber | | see [`Fiber`](@ref) |
 | ``\mathbb F`` | a field, usually ``\mathbb F \in \{\mathbb R,\mathbb C, \mathbb H\}``, i.e. the real, complex, and quaternion numbers, respectively. | |field a manifold or a basis is based on |
 | ``\gamma`` | a geodesic | ``\gamma_{p;q}``, ``\gamma_{p,X}`` | connecting two points ``p,q`` or starting in ``p`` with velocity ``X``. |
 | ``\operatorname{grad} f(p)`` | (Riemannian) gradient of function ``f \colon \mathcal{M} \to \mathbb{R}`` at ``p \in \mathcal{M}`` | | |

ext/ManifoldsRecipesBaseExt.jl

@@ -2,13 +2,15 @@ module ManifoldsRecipesBaseExt
 
 if isdefined(Base, :get_extension)
     using Manifolds
+    using Manifolds: TypeParameter
 
     using Colors: RGBA
     using RecipesBase: @recipe, @series
 else
     # imports need to be relative for Requires.jl-based workflows:
     # https://github.com/JuliaArrays/ArrayInterface.jl/pull/387
     using ..Manifolds
+    using ..Manifolds: TypeParameter
 
     using ..RecipesBase: @recipe, @series
     using ..Colors: RGBA
@@ -24,7 +26,7 @@ SURFACE_RESOLUTION_DEFAULT = 32
 # Plotting Recipe – Poincaré Ball
 #
 @recipe function f(
-    M::Hyperbolic{2},
+    M::Hyperbolic{TypeParameter{Tuple{2}}},
     pts::AbstractVector{P},
     vecs::Union{AbstractVector{T},Nothing}=nothing;
     circle_points=CIRCLE_DEFAULT_PLOT_POINTS,
@@ -87,7 +89,7 @@ end
 # Plotting Recipe – Poincaré Half plane
 #
 @recipe function f(
-    M::Hyperbolic{2},
+    M::Hyperbolic{TypeParameter{Tuple{2}}},
     pts::AbstractVector{P},
     vecs::Union{AbstractVector{T},Nothing}=nothing;
     geodesic_interpolation=-1,
@@ -133,7 +135,7 @@ end
 # Plotting Recipe – Hyperboloid
 #
 @recipe function f(
-    M::Hyperbolic{2},
+    M::Hyperbolic{TypeParameter{Tuple{2}}},
     pts::Union{AbstractVector{P},Nothing}=nothing,
     vecs::Union{AbstractVector{T},Nothing}=nothing;
     geodesic_interpolation=-1,
@@ -229,7 +231,7 @@ end
 # Plotting Recipe – Sphere
 #
 @recipe function f(
-    M::Sphere{2,ℝ},
+    M::Sphere{TypeParameter{Tuple{2}},ℝ},
     pts::Union{AbstractVector{P},Nothing}=nothing,
     vecs::Union{AbstractVector{T},Nothing}=nothing;
     geodesic_interpolation=-1,