Introduce Weingarten and riemannian_Hessian for a few manifolds (#…

…644)

* Start using DocumeterCitations.jl
* Introduce Weingarten for Sphere, Stiefel, and Grassmann.
* Introduce new notation.
* Introduce Hessian and Gradient notation
* Add Stiefel Euclidean.
* Add Grassmann and FixedRank
* add Rotations.
* Submersion and Canonical Metric on Stiefel. Fix a few docs.
* Add hessian conversion to unitary matrices and positive numbers.
* Apply suggestions from code review

---------

Co-authored-by: Mateusz Baran <mateuszbaran89@gmail.com>

.gitignore

@@ -13,3 +13,4 @@ tutorials/_freeze
 accuracy/*_files
 accuracy/_freeze
 accuracy/.quarto
+docs/src/tutorials/hand-gestures_files/figure-commonmark

CITATION.bib

@@ -1,9 +1,11 @@
-@online{2106.08777,
+@article{AxenBaranBergmannRzecki:2023,
     AUTHOR     = {Seth D. Axen and Mateusz Baran and Ronny Bergmann and Krzysztof Rzecki},
+    EPRINT     = {2021.08777},
+    EPRINTTYPE = {arXiv},
+    JOURNAL    = {AMS Transactions on Mathematical Software},
+    NOTE       = {accepted for publication},
     TITLE      = {Manifolds.jl: An Extensible {J}ulia Framework for Data Analysis on Manifolds},
-    YEAR       = {2021},
-    EPRINT     = {2106.08777},
-    EPRINTTYPE = {arXiv}
+    YEAR       = {2023}
 }
 @softawre{manifoldsjl-zenodo-mostrecent,
     AUTHOR    = {Seth D. Axen and Mateusz Baran and Ronny Bergmann},

Project.toml

@@ -42,14 +42,15 @@ ManifoldsRecipesBaseExt = ["Colors", "RecipesBase"]
 ManifoldsTestExt = "Test"
 
 [compat]
+BoundaryValueDiffEq = "3"
 Colors = "0.12"
 Distributions = "0.22.6, 0.23, 0.24, 0.25"
 Einsum = "0.4"
 Graphs = "1.4"
 HybridArrays = "0.4"
 Kronecker = "0.4, 0.5"
-ManifoldDiff = "0.3.3"
-ManifoldsBase = "0.14.1"
+ManifoldDiff = "0.3.6"
+ManifoldsBase = "0.14.11"
 MatrixEquations = "2.2"
 OrdinaryDiffEq = "6.31"
 Plots = "1"

README.md

@@ -56,12 +56,14 @@ If you have any questions regarding the Manifolds.jl ecosystem feel free to reac
 If you use `Manifolds.jl` in your work, please cite the following
 
 ```biblatex
-@online{2106.08777,
-  Author = {Seth D. Axen and Mateusz Baran and Ronny Bergmann and Krzysztof Rzecki},
-  Title = {Manifolds.jl: An Extensible {J}ulia Framework for Data Analysis on Manifolds},
-  Year = {2021},
-  Eprint = {2106.08777},
-  Eprinttype = {arXiv},
+@article{AxenBaranBergmannRzecki:2023,
+    AUTHOR     = {Seth D. Axen and Mateusz Baran and Ronny Bergmann and Krzysztof Rzecki},
+    EPRINT     = {2021.08777},
+    EPRINTTYPE = {arXiv},
+    JOURNAL    = {AMS Transactions on Mathematical Software},
+    NOTE       = {accepted for publication},
+    TITLE      = {Manifolds.jl: An Extensible {J}ulia Framework for Data Analysis on Manifolds},
+    YEAR       = {2023}
 }
 ```
 

docs/Project.toml

@@ -5,6 +5,7 @@ CondaPkg = "992eb4ea-22a4-4c89-a5bb-47a3300528ab"
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 FiniteDifferences = "26cc04aa-876d-5657-8c51-4c34ba976000"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 HybridArrays = "1baab800-613f-4b0a-84e4-9cd3431bfbb9"
@@ -19,7 +20,7 @@ StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
-BoundaryValueDiffEq = "2"
+BoundaryValueDiffEq = "3"
 CondaPkg = "0.2"
 DiffEqCallbacks = "2"
 Distributions = "0.22.6, 0.23, 0.24, 0.25"

docs/make.jl

@@ -34,6 +34,7 @@ end
 
 # (c) load necessary packages for the docs
 using Plots, RecipesBase, Manifolds, ManifoldsBase, Documenter, PythonPlot
+using DocumenterCitations
 # required for loading methods that handle differential equation solving
 using OrdinaryDiffEq, BoundaryValueDiffEq, DiffEqCallbacks
 # required for loading the manifold tests functions
@@ -61,7 +62,9 @@ open(joinpath(generated_path, "contributing.md"), "w") do io
 end
 
 # (e) ...finally! make docs
+bib = CitationBibliography(joinpath(@__DIR__, "src", "references.bib"); style=:alpha)
 makedocs(
+    bib;
     # for development, we disable prettyurls
     format=Documenter.HTML(prettyurls=false, assets=["assets/favicon.ico"]),
     modules=[
@@ -159,6 +162,7 @@ makedocs(
             "Contributing" => "misc/contributing.md",
             "Internals" => "misc/internals.md",
             "Notation" => "misc/notation.md",
+            "References" => "misc/references.md",
         ],
     ],
 )

docs/src/features/statistics.md

@@ -7,3 +7,8 @@ Order = [:type, :function]
 ```
 
 ## Literature
+
+```@bibliography
+Pages = ["features/statistics.md"]
+Canonical=false
+```

docs/src/manifolds/fixedrankmatrices.md

@@ -7,3 +7,8 @@ Order = [:type, :function]
 ```
 
 ## Literature
+
+```@bibliography
+Pages = ["manifolds/fixedrankmatrices.md"]
+Canonical=false
+```

docs/src/manifolds/grassmann.md

@@ -21,3 +21,11 @@ Modules = [Manifolds]
 Pages = ["manifolds/GrassmannProjector.jl"]
 Order = [:type,:function]
 ```
+
+
+## Literature
+
+```@bibliography
+Pages = ["manifolds/grassmann.md"]
+Canonical=false
+```

docs/src/manifolds/group.md

@@ -255,4 +255,4 @@ Order = [:type, :function]
 Modules = [Manifolds]
 Pages = ["groups/connections.jl"]
 Order = [:type, :function]
-```
+```

docs/src/manifolds/hyperbolic.md

@@ -176,3 +176,10 @@ And we can again look at the corresponding geodesics, for example
 plot!(scene, M, [pts[1], origin], geodesic_interpolation=100)
 plot!(scene, M, [pts[2], origin], geodesic_interpolation=100)
 ```
+
+## Literature
+
+```@bibliography
+Pages = ["manifolds/hyperbolic.md"]
+Canonical=false
+```

docs/src/manifolds/probabilitysimplex.md

@@ -1,13 +1,15 @@
 # The probability simplex
 
 ```@autodocs
-Modules = [Manifolds]
+Modules = [Manifolds, Base]
 Pages = ["manifolds/ProbabilitySimplex.jl"]
 Order = [:type, :function]
 Private=false
 Public=true
 ```
 
+## Euclidean metric
+
 ```@autodocs
 Modules = [Manifolds]
 Pages = ["manifolds/ProbabilitySimplexEuclideanMetric.jl"]
@@ -24,7 +26,7 @@ An isometric embedding of interior of [`ProbabilitySimplex`](@ref) in positive o
 
 This embedding isometrically maps the Fisher-Rao metric on the open probability simplex to
 the sphere of radius 1 with Euclidean metric. More details can be found in Section 2.2
-of [^AyJostLeSchwachhöfer2017].
+of [AyJostLeSchwachhoefer:2017](@cite).
 
 The name derives from the notion of probability amplitudes in quantum mechanics.
 They are complex-valued and their squared norm corresponds to probability. This construction
@@ -39,3 +41,8 @@ Public=false
 ```
 
 ## Literature
+
+```@bibliography
+Pages = ["manifolds/probabilitysimplex.md"]
+Canonical=false
+```

docs/src/manifolds/rotations.md

@@ -37,3 +37,8 @@ Order = [:type, :function]
 ```
 
 ## Literature
+
+```@bibliography
+Pages = ["manifolds/rotations.md"]
+Canonical=false
+```

docs/src/manifolds/sphere.md

@@ -62,3 +62,10 @@ p3 = 1/sqrt(3) .* [1.0, -1.0, 1.0]
 vecs = log.(Ref(M), pts2, Ref(p3))
 plot!(scene, M, pts2, vecs; wireframe = false, linewidth=1.5)
 ```
+
+## Literature
+
+```@bibliography
+Pages = ["manifolds/sphere.md"]
+Canonical=false
+```

docs/src/manifolds/stiefel.md

@@ -65,3 +65,8 @@ Private = true
 ```
 
 ## Literature
+
+```@bibliography
+Pages = ["manifolds/stiefel.md"]
+Canonical=false
+```

docs/src/manifolds/symmetricpositivedefinite.md

@@ -13,7 +13,7 @@ The manifold can be equipped with different metrics
 ## Common and metric independent functions
 
 ```@autodocs
-Modules = [Manifolds]
+Modules = [Manifolds, ManifoldsBase]
 Pages = ["manifolds/SymmetricPositiveDefinite.jl"]
 Order = [:function]
 Public=true

docs/src/manifolds/symplectic.md

@@ -1,34 +1,34 @@
-# Symplectic 
+# Symplectic
 
-The [`Symplectic`](@ref) manifold, denoted $\operatorname{Sp}(2n, \mathbb{F})$, is a closed, embedded, submanifold of 
+The [`Symplectic`](@ref) manifold, denoted $\operatorname{Sp}(2n, \mathbb{F})$, is a closed, embedded, submanifold of
 $\mathbb{F}^{2n \times 2n}$ that represents transformations into symplectic subspaces which keep the
 canonical symplectic form over $\mathbb{F}^{2n \times 2n }$ invariant under the standard embedding inner product.
-The canonical symplectic form is a non-degenerate bilinear and skew symmetric map 
-$\omega\colon \mathbb{F}^{2n} \times \mathbb{F}^{2n} 
+The canonical symplectic form is a non-degenerate bilinear and skew symmetric map
+$\omega\colon \mathbb{F}^{2n} \times \mathbb{F}^{2n}
 \rightarrow \mathbb{F}$, given by
 $\omega(x, y) = x^T Q_{2n} y$ for elements $x, y \in \mathbb{F}^{2n}$, with
 ````math
-    Q_{2n} = 
+    Q_{2n} =
     \begin{bmatrix}
      0_n  &  I_n \\
     -I_n  &  0_n
     \end{bmatrix}.
-```` 
-That means that an element $p \in \operatorname{Sp}(2n)$ must fulfill the requirement that 
+````
+That means that an element $p \in \operatorname{Sp}(2n)$ must fulfill the requirement that
 ````math
     \omega (p x, p y) = x^T(p^TQp)y = x^TQy = \omega(x, y),
 ````
 leading to the requirement on $p$ that $p^TQp = Q$.
 
-The symplectic manifold also forms a group under matrix multiplication, called the $\textit{symplectic group}$. 
-Since all the symplectic matrices necessarily have determinant one, the [symplectic group](https://en.wikipedia.org/wiki/Symplectic_group) 
-$\operatorname{Sp}(2n, \mathbb{F})$ is a subgroup of the special linear group, $\operatorname{SL}(2n, \mathbb{F})$. When the underlying 
+The symplectic manifold also forms a group under matrix multiplication, called the $\textit{symplectic group}$.
+Since all the symplectic matrices necessarily have determinant one, the [symplectic group](https://en.wikipedia.org/wiki/Symplectic_group)
+$\operatorname{Sp}(2n, \mathbb{F})$ is a subgroup of the special linear group, $\operatorname{SL}(2n, \mathbb{F})$. When the underlying
 field is either $\mathbb{R}$ or $\mathbb{C}$ the symplectic group with a manifold structure constitutes a Lie group, with the Lie
-Algebra 
+Algebra
 ````math
     \mathfrak{sp}(2n,F) = \{H \in \mathbb{F}^{2n \times 2n} \;|\; Q H + H^{T} Q = 0\}.
 ````
-This set is also known as the [Hamiltonian matrices](https://en.wikipedia.org/wiki/Hamiltonian_matrix), which have the 
+This set is also known as the [Hamiltonian matrices](https://en.wikipedia.org/wiki/Hamiltonian_matrix), which have the
 property that $(QH)^T = QH$ and are commonly used in physics.
 
 ```@autodocs
@@ -38,3 +38,8 @@ Order = [:type, :function]
 ```
 
 ## Literature
+
+```@bibliography
+Pages = ["manifolds/symplectic.md"]
+Canonical=false
+```

docs/src/manifolds/symplecticstiefel.md

@@ -1,20 +1,20 @@
 # Symplectic Stiefel
 
-The [`SymplecticStiefel`](@ref) manifold, denoted $\operatorname{SpSt}(2n, 2k)$, 
-represents canonical symplectic bases of $2k$ dimensonal symplectic subspaces of $\mathbb{R}^{2n \times 2n}$. 
-This means that the columns of each element $p \in \operatorname{SpSt}(2n, 2k) \subset \mathbb{R}^{2n \times 2k}$ 
-constitute a canonical symplectic basis of $\operatorname{span}(p)$. 
-The canonical symplectic form is a non-degenerate, bilinear, and skew symmetric map 
-$\omega_{2k}\colon \mathbb{F}^{2k} \times \mathbb{F}^{2k} 
+The [`SymplecticStiefel`](@ref) manifold, denoted $\operatorname{SpSt}(2n, 2k)$,
+represents canonical symplectic bases of $2k$ dimensonal symplectic subspaces of $\mathbb{R}^{2n \times 2n}$.
+This means that the columns of each element $p \in \operatorname{SpSt}(2n, 2k) \subset \mathbb{R}^{2n \times 2k}$
+constitute a canonical symplectic basis of $\operatorname{span}(p)$.
+The canonical symplectic form is a non-degenerate, bilinear, and skew symmetric map
+$\omega_{2k}\colon \mathbb{F}^{2k} \times \mathbb{F}^{2k}
 \rightarrow \mathbb{F}$, given by
 $\omega_{2k}(x, y) = x^T Q_{2k} y$ for elements $x, y \in \mathbb{F}^{2k}$, with
 ````math
-    Q_{2k} = 
+    Q_{2k} =
     \begin{bmatrix}
      0_k  &  I_k \\
     -I_k  &  0_k
     \end{bmatrix}.
-```` 
+````
 Specifically given an element $p \in \operatorname{SpSt}(2n, 2k)$ we require that
 ````math
     \omega_{2n} (p x, p y) = x^T(p^TQ_{2n}p)y = x^TQ_{2k}y = \omega_{2k}(x, y) \;\forall\; x, y \in \mathbb{F}^{2k},
@@ -29,3 +29,8 @@ Order = [:type, :function]
 ```
 
 ## Literature
+
+```@bibliography
+Pages = ["manifolds/symplecticstiefel.md"]
+Canonical=false
+```

docs/src/misc/internals.md

@@ -14,9 +14,19 @@ Manifolds.nzsign
 Manifolds.realify
 Manifolds.realify!
 Manifolds.select_from_tuple
+Manifolds.symmetrize
+Manifolds.symmetrize!
 Manifolds.unrealify!
 Manifolds.usinc
 Manifolds.usinc_from_cos
 Manifolds.vec2skew!
 Manifolds.ziptuples
 ```
+
+## Types in Extensions
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["../ext/ManifoldsOrdinaryDiffEqDiffEqCallbacksExt.jl"]
+Order = [:type, :function]
+```

docs/src/misc/notation.md

@@ -25,9 +25,12 @@ Within the documented functions, the utf8 symbols are used whenever possible, as
 | ``F`` | a fiber | | see [`VectorBundleFibers`](@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``. |
-| ``∇ f(p)`` | gradient of function ``f \colon \mathcal{M} \to \mathbb{R}`` at ``p \in \mathcal{M}`` | | |
+| ``\operatorname{grad} f(p)`` | (Riemannian) gradient of function ``f \colon \mathcal{M} \to \mathbb{R}`` at ``p \in \mathcal{M}`` | | |
+| ``\nabla f(p)`` | (Euclidean) gradient of function ``f \colon \mathcal{M} \to \mathbb{R}`` at ``p \in \mathcal{M}`` but thought of as evaluated in the embedding | `G` | |
 | ``\circ`` | a group operation | |
 | ``\cdot^\mathrm{H}`` | Hermitian or conjugate transposed for both complex or quaternion matrices| |
+| ``\operatorname{Hess} f(p)`` | (Riemannian) Hessian of function ``f \colon T_p\mathcal{M} \to T_p\mathcal M`` (i.e. the 1-1-tensor form) at ``p \in \mathcal{M}`` | | |
+| ``\nabla^2 f(p)`` | (Euclidean) Hessian of function ``f`` in the embedding | `H` | |
 | ``e`` | identity element of a group | |
 | ``I_k`` | identity matrix of size ``k\times k`` | |
 | ``k`` | indices | ``i,j`` | |
@@ -37,6 +40,8 @@ Within the documented functions, the utf8 symbols are used whenever possible, as
 | ``\mathcal{G}`` | a (Lie) group | |
 | ``\log_p q`` | logarithmic map at ``p \in \mathcal M`` of a point ``q \in \mathcal M`` | ``\log_p(q)`` | |
 | ``\mathcal M`` | a manifold | ``\mathcal M_1, \mathcal M_2,\ldots,\mathcal N`` | |
+| ``N_p \mathcal M`` | the normal space of the tangent space ``T_p \mathcal M`` in some embedding ``\mathcal E`` that should be clear from context | | |
+| ``V`` | a normal vector from ``N_p \mathcal M`` | ``W`` | |
 | ``\operatorname{Exp}`` | the matrix exponential | |
 | ``\operatorname{Log}`` | the matrix logarithm | |
 | ``\mathcal P_{q\gets p}X`` | parallel transport | | of the vector ``X`` from ``T_p\mathcal M`` to ``T_q\mathcal M``
@@ -52,7 +57,8 @@ Within the documented functions, the utf8 symbols are used whenever possible, as
 | ``e_i \in \mathbb R^n`` | the ``i``th unit vector | ``e_i^n`` | the space dimension (``n``) is omited, when clear from context
 | ``B`` | a vector bundle | |
 | ``\mathcal T_{q\gets p}X`` | vector transport | | of the vector ``X`` from ``T_p\mathcal M`` to ``T_q\mathcal M``
-| ``\mathcal T_{p,Y}X`` | vector transport in direction ``Y`` | | of the vector ``X`` from ``T_p\mathcal M`` to ``T_q\mathcal M``, where ``q`` is deretmined by ``Y``, for example using the exponential map or some retraction.
+| ``\mathcal T_{p,Y}X`` | vector transport in direction ``Y`` | | of the vector ``X`` from ``T_p\mathcal M`` to ``T_q\mathcal M``, where ``q`` is deretmined by ``Y``, for example using the exponential map or some retraction. |
 | ``\operatorname{Vol}(\mathcal M)`` | volume of manifold ``\mathcal M`` | |
 | ``\theta_p(X)`` | volume density for vector ``X`` tangent at point ``p`` | |
+| ``\mathcal W`` | the Weingarten map ``\mathcal W: T_p\mathcal M × N_p\mathcal M → T_p\mathcal M`` | ``\mathcal W_p`` | the second notation to emphasize the dependency of the point ``p\in\mathcal M`` |
 | ``0_k`` | the ``k\times k`` zero matrix. | |

docs/src/misc/references.md

@@ -0,0 +1,10 @@
+# Literature
+
+We are slowly moving to using [`DocumenterCitations.jl`](https://github.com/JuliaDocs/DocumenterCitations.jl/).
+The goal is to have all references used / mentioned in the documentation of Manifolds.jl also listed here.
+If you notice a reference still defined in a footnote, please change it into a BibTeX reference and [open a PR](https://github.com/JuliaManifolds/Manifolds.jl/compare)
+
+Usually you will find a small reference section at the end of every documentation page that contains references for just that page.
+
+```@bibliography
+```