📚

.JuliaFormatter.toml

@@ -8,3 +8,4 @@ whitespace_in_kwargs = false
 remove_extra_newlines = true
 annotate_untyped_fields_with_any = false
 conditional_to_if = false
+ignore = ["tutorials"]

.github/workflows/documenter.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: 1.6
+          version: 1.8
       - uses: julia-actions/julia-docdeploy@v1
         env:
           PYTHON: ""

.gitignore

@@ -5,3 +5,4 @@ docs/src/generated
 docs/src/misc/contributing.md
 benchmark/tune.json
 benchmark/results*
+docs/src/tutorials/*.md

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.36"
+version = "0.8.37"
 
 [deps]
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"

docs/Project.toml

@@ -10,6 +10,7 @@ Manifolds = "1cead3c2-87b3-11e9-0ccd-23c62b72b94e"
 ManifoldsBase = "3362f125-f0bb-47a3-aa74-596ffd7ef2fb"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+PlutoStaticHTML = "359b1769-a58e-495b-9770-312e911026ad"
 PyPlot = "d330b81b-6aea-500a-939a-2ce795aea3ee"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
@@ -27,3 +28,4 @@ OrdinaryDiffEq = "6"
 Plots = "1"
 PyPlot = "2.9"
 StaticArrays = "1.0"
+PlutoStaticHTML = "6.0.3"

docs/make.jl

@@ -1,4 +1,5 @@
 using Plots, RecipesBase, Manifolds, ManifoldsBase, Documenter, PyPlot
+using PlutoStaticHTML
 # required for loading methods that handle differential equation solving
 using OrdinaryDiffEq, BoundaryValueDiffEq, DiffEqCallbacks
 # required for loading the manifold tests functions
@@ -26,6 +27,46 @@ open(joinpath(generated_path, "contributing.md"), "w") do io
     end
 end
 
+#
+# Generate Pluto Tutorial HTMLs
+tutorial_menu = Array{Pair{String,String},1}()
+tutorial_src_folder = joinpath(@__DIR__, "..", "tutorials/")
+tutorial_output_folder = joinpath(@__DIR__, "src/", "tutorials/")
+tutorial_relative_path = "tutorials/"
+mkpath(tutorial_output_folder)
+@info tutorial_src_folder
+#
+# Tutorials
+@info " \n      Rendering Tutorials\n "
+tutorials = [
+    Dict(:file => "getstarted", :title => "Get started with Manifolds.jl"),
+    # Optional loading of packages (GLMakie) required
+    # Dict(:file => "working-in-charts", :title => "Working in charts"),
+]
+# build menu and write files myself - tp set edit url correctly.
+for t in tutorials
+    global tutorial_menu
+    rendered = build_notebooks( #though not really parallel here
+        BuildOptions(
+            tutorial_src_folder;
+            output_format=documenter_output,
+            write_files=false,
+            use_distributed=true,
+        ),
+        ["$(t[:file]).jl"],
+    )
+    write(
+        tutorial_output_folder * t[:file] * ".md",
+        """
+        ```@meta
+        EditURL = "$(tutorial_src_folder)$(t[:file]).jl"
+        ```
+        $(rendered["$(t[:file]).jl"][1])
+        """,
+    )
+    push!(tutorial_menu, t[:title] => joinpath(tutorial_relative_path, t[:file] * ".md"))
+end
+
 makedocs(
     # for development, we disable prettyurls
     format=Documenter.HTML(prettyurls=false, assets=["assets/favicon.ico"]),
@@ -34,6 +75,7 @@ makedocs(
     sitename="Manifolds.jl",
     pages=[
         "Home" => "index.md",
+        "Tutorials" => tutorial_menu,
         "Manifolds" => [
             "Basic manifolds" => [
                 "Centered matrices" => "manifolds/centeredmatrices.md",

docs/src/features/utilities.md

@@ -7,6 +7,16 @@ in
 TangentSpace
 ````
 
+# 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.
+
+```@autodocs
+Modules = [Manifolds]
+Pages = ["nlsolve.jl"]
+Order = [:type, :function]
+```
+
 # Public documentation
 
 The following functions are of interest for extending and using the [`ProductManifold`](@ref).

docs/src/index.md

@@ -1,6 +1,9 @@
 # Manifolds
 
-The package __Manifolds__ aims to provide a library of manifolds to be used within your project.
+```@docs
+Manifolds.Manifolds
+```
+
 The implemented manifolds are accompanied by their mathematical formulae.
 
 The manifolds are implemented using the interface for manifolds given in [`ManifoldsBase.jl`](https://juliamanifolds.github.io/ManifoldsBase.jl/).

src/Manifolds.jl

@@ -1,3 +1,6 @@
+"""
+`Manifolds.jl` provides a library of manifolds aiming for an easy-to-use and fast implementation.
+"""
 module Manifolds
 
 import ManifoldsBase:
@@ -559,7 +562,8 @@ export AbstractPowerManifold,
     QuotientManifold
 export ProductManifold, EmbeddedManifold
 export GraphManifold, GraphManifoldType, VertexManifold, EdgeManifold
-export ProjectedPointDistribution, ProductRepr, TangentBundle, TangentBundleFibers
+export ProductRepr, ArrayPartition
+export ProjectedPointDistribution, TangentBundle, TangentBundleFibers
 export TangentSpace, TangentSpaceAtPoint, VectorSpaceAtPoint, VectorSpaceType, VectorBundle
 export VectorBundleFibers
 export AbstractVectorTransportMethod,

src/differentiation/bvp.jl

@@ -22,7 +22,7 @@ end
         kwargs...,
     )
 
-Solve the BVP corresponding to geodesic calculation on [`AbstractManifold`](@ref) M,
+Solve the BVP corresponding to geodesic calculation on [`AbstractManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#ManifoldsBase.AbstractManifold) M,
 between points with parameters `a1` and `a2` in a chart `i` of an [`AbstractAtlas`](@ref) `A`
 using solver `solver`. Geodesic γ is sampled at time interval `dt`, with γ(0) = a1 and
 γ(1) = a2.
@@ -66,8 +66,8 @@ end
         kwargs...,
     )
 
-Estimate distance between points on [`AbstractManifold`](@ref) M with parameters `a1` and
-`a2` in chart `i` of [`AbstractAtlas`](@ref) `A` using solver `solver`, employing 
+Estimate distance between points on [`AbstractManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#ManifoldsBase.AbstractManifold) M with parameters `a1` and
+`a2` in chart `i` of [`AbstractAtlas`](@ref) `A` using solver `solver`, employing
 [`solve_chart_log_bvp`](@ref) to solve the geodesic BVP.
 """
 function estimate_distance_from_bvp(

src/differentiation/riemannian_diff.jl

@@ -135,7 +135,7 @@ end
 This method uses the internal `backend.diff_backend` (Euclidean) on the function
 
 ```math
-    f(\retr_p(\cdot))
+    f(\operatorname{retr}_p(\cdot))
 ```
 
 which is given on the tangent space. In detail, the gradient can be written in

src/groups/connections.jl

@@ -9,7 +9,7 @@ going through group identity are one-parameter subgroups. See[^Pennec2020] for d
     > X. Pennec and M. Lorenzi, “5 - Beyond Riemannian geometry: The affine connection
     > setting for transformation groups,” in Riemannian Geometric Statistics in Medical Image
     > Analysis, X. Pennec, S. Sommer, and T. Fletcher, Eds. Academic Press, 2020, pp. 169–229.
-    > doi: 10.1016/B978-0-12-814725-2.00012-1.
+    > doi: [10.1016/B978-0-12-814725-2.00012-1](https://doi.org/10.1016/B978-0-12-814725-2.00012-1).
 """
 abstract type AbstractCartanSchoutenConnection <: AbstractAffineConnection end
 

src/manifolds/FixedRankMatrices.jl

@@ -84,9 +84,11 @@ Base.:(==)(x::SVDMPoint, y::SVDMPoint) = (x.U == y.U) && (x.S == y.S) && (x.Vt =
 @doc raw"""
     UMVTVector <: TVector
 
-A tangent vector that can be described as a product `U_p M V_p^\mathrm{H} + U_X V_p^\mathrm{H} + U_p V_X^\mathrm{H}`,
-where `X = U_X S V_X^\mathrm{H}` is its base point, see for example [`FixedRankMatrices`](@ref).
-This vector structure stores the additionally (to the point) required fields.
+A tangent vector that can be described as a product ``U_p M V_p^\mathrm{H} + U_X V_p^\mathrm{H} + U_p V_X^\mathrm{H}``,
+where ``X = U_X S V_X^\mathrm{H}`` is its base point, see for example [`FixedRankMatrices`](@ref).
+
+The base point ``p`` is required for example embedding this point, but it is not stored.
+The fields of thie tangent vector are `U` for ``U_X``, `M` and `Vt` to store ``V_X^\mathrm{H}``
 
 # Constructors
 * `UMVTVector(U,M,Vt)` store umv factors to initialize the `UMVTVector`
@@ -288,8 +290,26 @@ function Base.copyto!(X::UMVTVector, Y::UMVTVector)
     return X
 end
 
-default_retraction_method(::FixedRankMatrices) = PolarRetraction()
+"""
+    default_inverse_retraction_method(M::Stiefel)
+
+Return [`PolarInverseRetraction`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/retractions.html#ManifoldsBase.PolarInverseRetraction) as the default inverse retraction for the
+[`FixedRankMatrices`](@ref) manifold.
+"""
 default_inverse_retraction_method(::FixedRankMatrices) = PolarInverseRetraction()
+
+"""
+    default_retraction_method(M::FixedRankMatrices)
+
+Return [`PolarRetraction`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/retractions.html#ManifoldsBase.PolarRetraction) as the default retraction for the [`FixedRankMatrices`](@ref) manifold.
+"""
+default_retraction_method(::FixedRankMatrices) = PolarRetraction()
+
+"""
+    default_vector_transport_method(M::FixedRankMatrices)
+
+Return the [`ProjectionTransport`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/vector_transports.html#ManifoldsBase.ProjectionTransport) as the default vector transport method for the [`FixedRankMatrices`](@ref) manifold.
+"""
 default_vector_transport_method(::FixedRankMatrices) = ProjectionTransport()
 
 @doc raw"""
@@ -409,7 +429,7 @@ end
     Random.rand(M::FixedRankMatrices; vector_at=nothing, kwargs...)
 
 If `vector_at` is `nothing`, return a random point on the [`FixedRankMatrices`](@ref)
-manifold. The orthogonal matrices are sampled from the [`Stiefel`(@ref) manifold
+manifold. The orthogonal matrices are sampled from the [`Stiefel`](@ref) manifold
 and the singular values are sampled uniformly at random.
 
 If `vector_at` is not `nothing`, generate a random tangent vector in the tangent space of

src/manifolds/GeneralUnitaryMatrices.jl

@@ -612,7 +612,7 @@ Return the dimension of the manifold orthogonal matrices and of the manifold of
 manifold_dimension(::GeneralUnitaryMatrices{n,ℝ}) where {n} = div(n * (n - 1), 2)
 @doc raw"""
     manifold_dimension(M::GeneralUnitaryMatrices{n,ℂ,DeterminantOneMatrices})
-    
+
 Return the dimension of the manifold of special unitary matrices.
 ```math
 \dim_{\mathrm{SU}(n)} = n^2-1.
@@ -731,7 +731,7 @@ The formula reads[^Rentmeesters2011] ``R(X,Y)Z=\frac{1}{4}[Z, [X, Y]]``.
 [^Rentmeesters2011]:
     > Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric
     > Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and
-    > European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.
+    > European Control Conference, Dec. 2011, pp. 7141–7146. doi: [10.1109/CDC.2011.6161280](https://doi.org/10.1109/CDC.2011.6161280).
 """
 riemann_tensor(::GeneralUnitaryMatrices, p, X, Y, Z)
 

src/manifolds/GrassmannProjector.jl

@@ -217,7 +217,7 @@ end
 Compute the horizontal lift of `X` from the tangent space at ``p=π(q)``
 on the [`Grassmann`](@ref) manifold, i.e.
 
-```
+```math
 Y = Xq ∈ T_q\mathrm{St}(n,k)
 ```
 

src/manifolds/GrassmannStiefel.jl

@@ -302,7 +302,7 @@ The formula reads[^Rentmeesters2011]
 [^Rentmeesters2011]:
     > Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric
     > Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and
-    > European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.
+    > European Control Conference, Dec. 2011, pp. 7141–7146. doi: [10.1109/CDC.2011.6161280](https://doi.org/10.1109/CDC.2011.6161280).
 """
 riemann_tensor(::Grassmann{n,k,ℝ}, p, X, Y, Z) where {n,k}
 

src/manifolds/Sphere.jl

@@ -482,7 +482,7 @@ R(X,Y)Z = \langle Z, Y \rangle X - \langle Z, X \rangle Y
 [^MuralidharanFletcher2021]:
     > P. Muralidharan and P. T. Fletcher, “Sasaki Metrics for Analysis of Longitudinal Data
     > on Manifolds,” Proc IEEE Comput Soc Conf Comput Vis Pattern Recognit, vol. 2012,
-    > pp. 1027–1034, Jun. 2012, doi: 10.1109/CVPR.2012.6247780.
+    > pp. 1027–1034, Jun. 2012, doi: [10.1109/CVPR.2012.6247780](https://doi.org/10.1109/CVPR.2012.6247780).
 """
 riemann_tensor(M::AbstractSphere{ℝ}, p, X, Y, Z)
 

src/manifolds/Stiefel.jl

@@ -87,22 +87,22 @@ end
 """
     default_inverse_retraction_method(M::Stiefel)
 
-Return [`PolarInverseRetraction`](@ref) as the default inverse retraction for the
+Return [`PolarInverseRetraction`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/retractions.html#ManifoldsBase.PolarInverseRetraction) as the default inverse retraction for the
 [`Stiefel`](@ref) manifold.
 """
 default_inverse_retraction_method(::Stiefel) = PolarInverseRetraction()
 
 """
     default_retraction_method(M::Stiefel)
 
-Return [`PolarRetraction`](@ref) as the default retraction for the [`Stiefel`](@ref) manifold.
+Return [`PolarRetraction`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/retractions.html#ManifoldsBase.PolarRetraction) as the default retraction for the [`Stiefel`](@ref) manifold.
 """
 default_retraction_method(::Stiefel) = PolarRetraction()
 
 """
     default_vector_transport_method(M::Stiefel)
 
-Return the [`DifferentiatedRetractionVectorTransport`](@ref) of the [`PolarRetraction`](@ref)
+Return the [`DifferentiatedRetractionVectorTransport`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/vector_transports.html#ManifoldsBase.DifferentiatedRetractionVectorTransport) of the [`PolarRetraction`]([`PolarRetraction`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/retractions.html#ManifoldsBase.PolarRetraction)
 as the default vector transport method for the [`Stiefel`](@ref) manifold.
 """
 function default_vector_transport_method(::Stiefel)

src/manifolds/StiefelSubmersionMetric.jl

@@ -135,7 +135,7 @@ end
         method::ShootingInverseRetraction,
     )
 
-Compute the inverse retraction using [`ShootingInverseRetraction`](@ref).
+Compute the inverse retraction using [`ShootingInverseRetraction`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/retractions.html#ManifoldsBase.ShootingInverseRetraction).
 
 In general the retraction is computed using the generic shooting method.
 
@@ -150,7 +150,7 @@ In general the retraction is computed using the generic shooting method.
         },
     )
 
-Compute the inverse retraction using [`ShootingInverseRetraction`](@ref) more efficiently.
+Compute the inverse retraction using [`ShootingInverseRetraction`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/retractions.html#ManifoldsBase.ShootingInverseRetraction) more efficiently.
 
 For ``k < \frac{n}{2}`` the retraction is computed more efficiently using
 [`StiefelFactorization`](@ref).
@@ -206,7 +206,7 @@ end
 
 Compute the logarithmic map on the [`Stiefel(n,k)`](@ref) manifold with respect to the [`StiefelSubmersionMetric`](@ref).
 
-The logarithmic map is computed using [`ShootingInverseRetraction`](@ref). For
+The logarithmic map is computed using [`ShootingInverseRetraction`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/retractions.html#ManifoldsBase.ShootingInverseRetraction). For
 ``k ≤ \lfloor\frac{n}{2}\rfloor``, this is sped up using the ``k``-shooting method of
 [^ZimmermanHüper2022]. Keyword arguments are forwarded to `ShootingInverseRetraction`; see
 that documentation for details. Their defaults are:

src/manifolds/SymmetricPositiveDefinite.jl

@@ -33,7 +33,7 @@ SymmetricPositiveDefinite(n::Int) = SymmetricPositiveDefinite{n}()
 @doc raw"""
     SPDPoint <: AbstractManifoldsPoint
 
-Store the result of `eigen(p)` of an SPD matrix and (optionally) ``p^{\frac{1}[2}}`` and ``p^{-\frac{1}[2}}``
+Store the result of `eigen(p)` of an SPD matrix and (optionally) ``p^{1/2}`` and ``p^{-1/2}``
 to avoid their repeated computations.
 
 This result only has the result of `eigen` as a mandatory storage, the other three
@@ -381,7 +381,7 @@ Base.eltype(p::SPDPoint) = eltype(p.eigen)
 @doc raw"""
     project(M::SymmetricPositiveDefinite, p, X)
 
-project a matrix from the embedding onto the tangent space $T_p\mathcal P(n)$ of the
+project a matrix from the embedding onto the tangent space ``T_p\mathcal P(n)`` of the
 [`SymmetricPositiveDefinite`](@ref) matrices, i.e. the set of symmetric matrices.
 """
 project(::SymmetricPositiveDefinite, p, X)

src/manifolds/SymmetricPositiveDefiniteLinearAffine.jl

@@ -411,7 +411,7 @@ The formula reads[^Rentmeesters2011] ``R(X,Y)Z=p^{1/2}R(X_I, Y_I)Z_Ip^{1/2}``, w
 [^Rentmeesters2011]:
     > Q. Rentmeesters, “A gradient method for geodesic data fitting on some symmetric
     > Riemannian manifolds,” in 2011 50th IEEE Conference on Decision and Control and
-    > European Control Conference, Dec. 2011, pp. 7141–7146. doi: 10.1109/CDC.2011.6161280.
+    > European Control Conference, Dec. 2011, pp. 7141–7146. doi: [10.1109/CDC.2011.6161280](https://doi.org/10.1109/CDC.2011.6161280).
 """
 riemann_tensor(::SymmetricPositiveDefinite, p, X, Y, Z)