JuliaManifolds · mateuszbaran · Aug 24, 2024 · Nov 13, 2023 · Nov 13, 2023 · Nov 13, 2023
diff --git a/NEWS.md b/NEWS.md
@@ -5,6 +5,41 @@ 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.10.0] – 2024-08-24
+
+### Changed
+
+* `Distributions.jl`, `RecursiveArrayTools.jl` and `HybridArrays.jl` were moved to weak dependencies to reduce load time and improve extensibility.
+* `translate_diff`, `inv_diff` and thus `apply_diff_group`, are available for all the groups with invariant tangent vector storage.
+* `SpecialEuclidean` group now has a different default tangent vector representation, the left-invariant one; to get the old representation pass `vectors=HybridTangentRepresentation()` to the constructor of `SpecialEuclidean`.
+* `adjoint_action` takes a direction argument; by default it is `LeftAction`.
+* `adjoint_action!` is the necessary method to implement in groups with left-invariant tangent vector representation.
+* Fixed a few typos in the doc string of the SPD fixed determinant description.
+* Random point on the `MultinomialSymmetricPositiveDefinite` manifold was improved to make it more robust.
+
+### Added
+
+* Introduced `exp_inv` and `log_inv` based on `exp_lie` and `log_lie`. They are invariant to the group operation.
+* A tutorial about usage of group-related functionality.
+
+### Removed
+
+* Deprecated bindings:
+  * `ExtrinsicEstimation()` (should be replaced with `ExtrinsicEstimation(EfficientEstimator())`),
+  * `Symplectic` (renamed to `SymplecticMatrices`),
+  * `SymplecticMatrix` (renamed to `SymplecticElement`).
+  * `AbstractEstimationMethod` (renamed to `AbstractApproximationMethod`).
+  * `VectorBundleVectorTransport` (renamed to `FiberBundleProductVectorTransport`).
+  * `rand` on `SymplecticMatrices` and `SymplecticStiefel` no longer accepts `hamiltonian_norm` as an alias for `σ`.
+  * `mean!` and `median!` no longer accept `extrinsic_method` (should be replaced with `e = ExtrinsicEstimation(extrinsic_method)`).
+* As a result of making `Distributions.jl` and `RecursiveArrayTools.jl` weak dependencies the following symbols are no longer exported from `Manifolds.jl`. Essential functionality is still available but distribution-related features may change in the future without a breaking release.
+  * `ArrayPartition` (`RecursiveArrayTools.jl` needs to be explicitly imported),
+  * `ProjectedPointDistribution` (not exported),
+  * `normal_tvector_distribution` (not exported),
+  * `projected_distribution` (not exported),
+  * `uniform_distribution` (not exported).
+* Ability to create non-real `SymplecticStiefel` and `SymplecticGrassmann` manifolds; essential functionality was missing so it was removed until a more developed version is developed.
+
 ## [0.9.20] – 2024-06-17
 
 ### Added

diff --git a/Project.toml b/Project.toml
@@ -1,13 +1,11 @@
 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.9.20"
+version = "0.10.0"
 
 [deps]
-Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Einsum = "b7d42ee7-0b51-5a75-98ca-779d3107e4c0"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
-HybridArrays = "1baab800-613f-4b0a-84e4-9cd3431bfbb9"
 Kronecker = "2c470bb0-bcc8-11e8-3dad-c9649493f05e"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 ManifoldDiff = "af67fdf4-a580-4b9f-bbec-742ef357defd"
@@ -16,7 +14,6 @@ Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 MatrixEquations = "99c1a7ee-ab34-5fd5-8076-27c950a045f4"
 Quaternions = "94ee1d12-ae83-5a48-8b1c-48b8ff168ae0"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
-RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 SimpleWeightedGraphs = "47aef6b3-ad0c-573a-a1e2-d07658019622"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
@@ -28,17 +25,23 @@ StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 BoundaryValueDiffEq = "764a87c0-6b3e-53db-9096-fe964310641d"
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+HybridArrays = "1baab800-613f-4b0a-84e4-9cd3431bfbb9"
 NLsolve = "2774e3e8-f4cf-5e23-947b-6d7e65073b56"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
+RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [extensions]
 ManifoldsBoundaryValueDiffEqExt = "BoundaryValueDiffEq"
+ManifoldsDistributionsExt = ["Distributions", "RecursiveArrayTools"]
+ManifoldsHybridArraysExt = "HybridArrays"
 ManifoldsNLsolveExt = "NLsolve"
-ManifoldsOrdinaryDiffEqDiffEqCallbacksExt = ["DiffEqCallbacks", "OrdinaryDiffEq"]
+ManifoldsOrdinaryDiffEqDiffEqCallbacksExt = ["DiffEqCallbacks", "OrdinaryDiffEq", "RecursiveArrayTools"]
 ManifoldsOrdinaryDiffEqExt = "OrdinaryDiffEq"
 ManifoldsRecipesBaseExt = ["Colors", "RecipesBase"]
+ManifoldsRecursiveArrayToolsExt = "RecursiveArrayTools"
 ManifoldsTestExt = "Test"
 
 [compat]
@@ -76,9 +79,11 @@ julia = "1.6"
 BoundaryValueDiffEq = "764a87c0-6b3e-53db-9096-fe964310641d"
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 DoubleFloats = "497a8b3b-efae-58df-a0af-a86822472b78"
 FiniteDifferences = "26cc04aa-876d-5657-8c51-4c34ba976000"
 Gtk = "4c0ca9eb-093a-5379-98c5-f87ac0bbbf44"
+HybridArrays = "1baab800-613f-4b0a-84e4-9cd3431bfbb9"
 ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 NLsolve = "2774e3e8-f4cf-5e23-947b-6d7e65073b56"
@@ -90,8 +95,9 @@ PythonPlot = "274fc56d-3b97-40fa-a1cd-1b4a50311bf9"
 QuartzImageIO = "dca85d43-d64c-5e67-8c65-017450d5d020"
 Quaternions = "94ee1d12-ae83-5a48-8b1c-48b8ff168ae0"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
+RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 VisualRegressionTests = "34922c18-7c2a-561c-bac1-01e79b2c4c92"
 
 [targets]
-test = ["Test", "BoundaryValueDiffEq", "Colors", "DiffEqCallbacks", "DoubleFloats", "FiniteDifferences", "Gtk", "ImageIO", "ImageMagick", "OrdinaryDiffEq", "NLsolve", "Plots", "PythonPlot", "Quaternions", "QuartzImageIO", "RecipesBase"]
+test = ["Test", "BoundaryValueDiffEq", "Colors", "DiffEqCallbacks", "Distributions", "DoubleFloats", "FiniteDifferences", "Gtk", "HybridArrays", "ImageIO", "ImageMagick", "OrdinaryDiffEq", "NLsolve", "Plots", "PythonPlot", "Quaternions", "QuartzImageIO", "RecipesBase", "RecursiveArrayTools"]
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -18,6 +18,7 @@ OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 PythonPlot = "274fc56d-3b97-40fa-a1cd-1b4a50311bf9"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
+RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
@@ -36,4 +37,5 @@ ManifoldsBase = "0.15.0"
 OrdinaryDiffEq = "6"
 Plots = "1"
 PythonPlot = "1"
+RecursiveArrayTools = "3"
 StaticArrays = "1.0"
diff --git a/docs/make.jl b/docs/make.jl
@@ -24,6 +24,7 @@ if "--quarto" ∈ ARGS
         tutorials_folder = (@__DIR__) * "/../tutorials"
         # instantiate the tutorials environment if necessary
         Pkg.activate(tutorials_folder)
+        Pkg.develop(PackageSpec(; path=(@__DIR__) * "/../"))
         Pkg.resolve()
         Pkg.instantiate()
         Pkg.activate(@__DIR__) # but return to the docs one before
@@ -110,6 +111,7 @@ makedocs(;
             "perform Hand gesture analysis" => "tutorials/hand-gestures.md",
             "integrate on manifolds and handle probability densities" => "tutorials/integration.md",
             "explore curvature without coordinates" => "tutorials/exploring-curvature.md",
+            "work with groups" => "tutorials/groups.md",
         ],
         "Manifolds" => [
             "Basic manifolds" => [

diff --git a/docs/src/manifolds/group.md b/docs/src/manifolds/group.md
@@ -43,6 +43,63 @@ Pages = ["groups/GroupManifold.jl"]
 Order = [:constant, :type, :function]
 ```
 
+### Default Representation of Tangent Vectors
+
+In most groups, the representation of a tangent vector
+ ``X`` at the point ``p ∈ \mathcal{G}`` is stored
+ as a vector ``Y ∈ \mathfrak{g}``.
+This helps to compute the derivatives of the composition and inverse.
+
+To explain this, let us assume that *the group consists of matrices* (this is always possible).
+The representation of a tangent vector
+ ``X`` at the point ``p ∈ \mathcal{G}`` is stored
+ as the vector ``Y ∈ \mathfrak{g}`` given by
+
+```math
+X = pY
+```
+
+#### Derivative of the Group Composition on the Left
+
+The derivative of the composition ``pq`` with respect to ``p`` in
+the direction ``X``, tangent at ``p`` is given by
+
+```math
+Xq = pYq = pq(q^{-1}Yq)
+```
+
+We see that with this representation convention, this derivative is just the
+adjoint action of ``q^{-1}`` on the vector ``Y``.
+
+#### Derivative of the Group Composition on the Right
+
+For the derivative with respect to ``q`` of the composition ``pq`` at a tangent vector ``X`` at ``q``
+stored as ``Y`` with ``X = qY``, we have similarly
+
+```math
+pX = pqY
+```
+
+With the representation convention above, this derivative is just the identity.
+
+#### Derivative of the Group Inverse
+
+Finally, we look at the derivative of the inverse ``p^{-1}`` at a point ``p`` in a tangent direction ``X``
+at ``p`` with ``X = pY``.
+The result is a tangent vector at ``p^{-1}`` given by
+
+```math
+-p^{-1}Xp^{-1} = - Yp^{-1} = -p^{-1}(p Y p^{-1})
+```
+
+With the representation convention above, this derivative is thus ``-pYp^{-1}``, that is, the opposite of the adjoint action of ``p`` on the vector ``Y``.
+
+#### Implication for Creating New Groups
+
+When you create a new group,
+defining the adjoint action alone ([`adjoint_action`](@ref))
+automatically defines all the relevant derivatives above.
+
 ### Generic Operations
 
 For groups based on an addition operation or a group operation, several default implementations are provided.

diff --git a/docs/src/manifolds/power.md b/docs/src/manifolds/power.md
@@ -90,7 +90,7 @@ get_component(M, p, 4)
 The final representation is the [`NestedReplacingPowerRepresentation`](@extref `ManifoldsBase.NestedReplacingPowerRepresentation`). It is similar to the [`NestedPowerRepresentation`](@extref `ManifoldsBase.NestedPowerRepresentation`) but it does not perform in-place operations on the points on the underlying manifold. The example below uses this representation to store points on a power manifold of the [`SpecialEuclidean`](@ref) group in-line in an `Vector` for improved efficiency. When having a mixture of both, i.e. an array structure that is nested (like [´NestedPowerRepresentation](@ref)) in the sense that the elements of the main vector are immutable, then changing the elements can not be done in an in-place way and hence [`NestedReplacingPowerRepresentation`](@extref `ManifoldsBase.NestedReplacingPowerRepresentation`) has to be used.
 
 ```@example 4
-using Manifolds, StaticArrays
+using Manifolds, StaticArrays, RecursiveArrayTools
 R2 = Rotations(2)
 
 G = SpecialEuclidean(2)

diff --git a/docs/src/manifolds/vector_bundle.md b/docs/src/manifolds/vector_bundle.md
@@ -26,7 +26,7 @@ Order = [:constant, :type, :function]
 The following code defines a point on the tangent bundle of the sphere ``S^2`` and a tangent vector to that point.
 
 ```@example tangent-bundle
-using Manifolds
+using Manifolds, RecursiveArrayTools
 M = Sphere(2)
 TB = TangentBundle(M)
 p = ArrayPartition([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])

diff --git a/docs/src/references.bib b/docs/src/references.bib
@@ -195,22 +195,6 @@ @article{LeBrignantPuechmorel:2019
 # C
 # ----------------------------------------------------------------------------------------
 
-@book{CheegerEbin:2008,
-	address = {Providence, R.I},
-	title = {Comparison {Theorems} in {Riemannian} {Geometry}},
-	isbn = {978-0-8218-4417-5},
-	publisher = {American Mathematical Society},
-	author = {Cheeger, Jeffrey and Ebin, David G.},
-	month = may,
-	year = {2008},
-}
-@book{Chikuse:2003,
-    DOI    = {10.1007/978-0-387-21540-2},
-    YEAR   = {2003},
-    AUTHOR = {Yasuko Chikuse},
-    PUBLISHER = {Springer New York},
-    TITLE  = {Statistics on Special Manifolds}
-}
 @inproceedings{ChakrabortyVemuri:2015,
     AUTHOR    = {Rudrasis Chakraborty and Baba C. Vemuri},
     BOOKTITLE = {2015 {IEEE} International Conference on Computer Vision (ICCV)},
@@ -229,6 +213,15 @@ @article{ChakrabortyVemuri:2019
     TITLE      = {Statistics on the Stiefel manifold: Theory and applications},
     JOURNAL    = {The Annals of Statistics}
 }
+@book{CheegerEbin:2008,
+	address = {Providence, R.I},
+	title = {Comparison {Theorems} in {Riemannian} {Geometry}},
+	isbn = {978-0-8218-4417-5},
+	publisher = {American Mathematical Society},
+	author = {Cheeger, Jeffrey and Ebin, David G.},
+	month = may,
+	year = {2008},
+}
 @incollection{ChengHoSalehianVemuri:2016,
     AUTHOR    = {Guang Cheng and Jeffrey Ho and Hesamoddin Salehian and Baba C. Vemuri},
     BOOKTITLE = {Riemannian Computing in Computer Vision},
@@ -255,6 +248,23 @@ @article{ChevallierLiLuDunson:2022
     URL = {https://doi.org/10.48550/arXiv.2009.01983},
     YEAR = {2022}
 }
+@book{Chikuse:2003,
+    DOI    = {10.1007/978-0-387-21540-2},
+    YEAR   = {2003},
+    AUTHOR = {Yasuko Chikuse},
+    PUBLISHER = {Springer New York},
+    TITLE  = {Statistics on Special Manifolds}
+}
+@book{Chirikjian:2012,
+	edition = {1},
+	series = {Applied and {Numerical} {Harmonic} {Analysis}},
+	title = {Stochastic {Models}, {Information} {Theory}, and {Lie} {Groups}, {Volume} 2},
+	volume = {2},
+	url = {https://link.springer.com/book/10.1007/978-0-8176-4944-9},
+	publisher = {Birkhäuser Boston, MA},
+	author = {Chirikjian, Gregory S.},
+	year = {2012},
+}
 #
 # D
 # ----------------------------------------------------------------------------------------
@@ -341,6 +351,21 @@ @article{GallierXu:2002
     URL = {http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.35.3205},
     YEAR = {2002}
 }
+
+@book{GallierQuaintance:2020,
+	address = {Cham},
+	series = {Geometry and {Computing}},
+	title = {Differential {Geometry} and {Lie} {Groups}: {A} {Computational} {Perspective}},
+	volume = {12},
+	isbn = {978-3-030-46039-6 978-3-030-46040-2},
+	url = {http://link.springer.com/10.1007/978-3-030-46040-2},
+	language = {en},
+	publisher = {Springer International Publishing},
+	author = {Gallier, Jean and Quaintance, Jocelyn},
+	year = {2020},
+	doi = {10.1007/978-3-030-46040-2},
+}
+
 @article{GaoSonAbsilStykel:2021,
     DOI     = {10.1137/20m1348522},
     YEAR    = {2021},
@@ -733,11 +758,16 @@ @article{Sasaki:1958
     TITLE   = {On the differential geometry of tangent bundles of Riemannian manifolds},
     JOURNAL = {Tohoku Math. J.}
 }
-@book{Suhubi:2013,
-    AUTHOR = {Suhubi, E},
-    PUBLISHER = {Academic Press},
-    TITLE = {Exterior Analysis: Using Applications of Differential Forms},
-    YEAR = {2013}
+@misc{SolaDerayAtchuthan:2021,
+	title = {A micro {Lie} theory for state estimation in robotics},
+	url = {http://arxiv.org/abs/1812.01537},
+	author = {Solà, Joan and Deray, Jeremie and Atchuthan, Dinesh},
+	month = dec,
+	year = {2021},
+	note = {arXiv: 1812.01537},
+    eprint={1812.01537},
+    archivePrefix={arXiv},
+    primaryClass={cs.RO},
 }
 @book{SrivastavaKlassen:2016,
     AUTHOR = {Anuj Srivastava and Eric P. Klassen},
@@ -747,6 +777,12 @@ @book{SrivastavaKlassen:2016
     TITLE  = {Functional and Shape Data Analysis},
     YEAR   = {2016}
 }
+@book{Suhubi:2013,
+    AUTHOR = {Suhubi, E},
+    PUBLISHER = {Academic Press},
+    TITLE = {Exterior Analysis: Using Applications of Differential Forms},
+    YEAR = {2013}
+}
 #
 # T
 # ----------------------------------------------------------------------------------------

diff --git a/ext/ManifoldsDistributionsExt/ManifoldsDistributionsExt.jl b/ext/ManifoldsDistributionsExt/ManifoldsDistributionsExt.jl
@@ -0,0 +1,41 @@
+module ManifoldsDistributionsExt
+
+if isdefined(Base, :get_extension)
+    using Manifolds
+    using Distributions
+    using Random
+    using LinearAlgebra
+
+    import Manifolds:
+        normal_rotation_distribution,
+        normal_tvector_distribution,
+        projected_distribution,
+        uniform_distribution
+
+    using Manifolds: get_iterator, get_parameter, _read, _write
+
+    using RecursiveArrayTools: ArrayPartition
+else
+    # imports need to be relative for Requires.jl-based workflows:
+    # https://github.com/JuliaArrays/ArrayInterface.jl/pull/387
+    using ..Manifolds
+    using ..Distributions
+    using ..Random
+    using ..LinearAlgebra
+
+    import ..Manifolds:
+        normal_rotation_distribution,
+        normal_tvector_distribution,
+        projected_distribution,
+        uniform_distribution
+
+    using ..Manifolds: get_iterator, get_parameter, _read, _write
+
+    using ..RecursiveArrayTools: ArrayPartition
+end
+
+include("distributions.jl")
+include("distributions_for_manifolds.jl")
+include("projected_distribution.jl")
+
+end