Towards integration on manifolds (#628)

* Start with integration tools * a bit of polishing and a sketch of Pelletier's KDE * some work on volumes * volumes of some groups * more volumes and densities * more volumes * volume density on Circle, SO(n), O(n) * fix normalization for volume of Rotations(n) * specialized volume_density on (S)O(2/3); minor cleanup * volume density for SPD * more docs * volumes on probability simplex and one more test * improve style * one more test * Move integration tutorial to quarto notebook * make Distributions a docs dependency * maybe now? * add SpecialFunction tutorial dep * expand docs on integration * minor improvements * volume + density on positive numbers * address review comments * Update tutorials/integration.qmd Co-authored-by: Ronny Bergmann <git@ronnybergmann.net> * address review comment * bump version --------- Co-authored-by: Ronny Bergmann <git@ronnybergmann.net>
JuliaManifolds · Aug 30, 2023 · a0c70ac · a0c70ac
1 parent 7afc7af
commit a0c70ac
Show file tree

Hide file tree

Showing 35 changed files with 912 additions and 16 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "Manifolds"
 uuid = "1cead3c2-87b3-11e9-0ccd-23c62b72b94e"
 authors = ["Seth Axen <seth.axen@gmail.com>", "Mateusz Baran <mateuszbaran89@gmail.com>", "Ronny Bergmann <manopt@ronnybergmann.net>", "Antoine Levitt <antoine.levitt@gmail.com>"]
-version = "0.8.74"
+version = "0.8.75"
 
 [deps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -3,6 +3,7 @@ BoundaryValueDiffEq = "764a87c0-6b3e-53db-9096-fe964310641d"
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 CondaPkg = "992eb4ea-22a4-4c89-a5bb-47a3300528ab"
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FiniteDifferences = "26cc04aa-876d-5657-8c51-4c34ba976000"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
@@ -21,6 +22,7 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 BoundaryValueDiffEq = "2"
 CondaPkg = "0.2"
 DiffEqCallbacks = "2"
+Distributions = "0.22.6, 0.23, 0.24, 0.25"
 Documenter = "0.27"
 FiniteDifferences = "0.12"
 Graphs = "1.4"

diff --git a/docs/make.jl b/docs/make.jl
@@ -91,6 +91,7 @@ makedocs(
             "🚀 Get Started with `Manifolds.jl`" => "tutorials/getstarted.md",
             "work in charts" => "tutorials/working-in-charts.md",
             "perform Hand gesture analysis" => "tutorials/hand-gestures.md",
+            "integrate on manifolds and handle probability densities" => "tutorials/integration.md",
         ],
         "Manifolds" => [
             "Basic manifolds" => [
@@ -148,6 +149,7 @@ makedocs(
             "Atlases and charts" => "features/atlases.md",
             "Differentiation" => "features/differentiation.md",
             "Distributions" => "features/distributions.md",
+            "Integration" => "features/integration.md",
             "Statistics" => "features/statistics.md",
             "Testing" => "features/testing.md",
             "Utilities" => "features/utilities.md",

diff --git a/docs/src/features/integration.md b/docs/src/features/integration.md
@@ -0,0 +1,6 @@
+# Integration
+
+```@docs
+manifold_volume(::AbstractManifold)
+volume_density(::AbstractManifold, ::Any, ::Any)
+```
diff --git a/docs/src/manifolds/probabilitysimplex.md b/docs/src/manifolds/probabilitysimplex.md
@@ -8,6 +8,15 @@ Private=false
 Public=true
 ```
 
+```@autodocs
+Modules = [Manifolds]
+Pages = ["manifolds/ProbabilitySimplexEuclideanMetric.jl"]
+Order = [:type, :function]
+Private=false
+Public=true
+```
+
+
 ## Real probability amplitudes
 
 An isometric embedding of interior of [`ProbabilitySimplex`](@ref) in positive orthant of the

diff --git a/docs/src/misc/notation.md b/docs/src/misc/notation.md
@@ -53,4 +53,6 @@ Within the documented functions, the utf8 symbols are used whenever possible, as
 | ``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.
+| ``\operatorname{Vol}(\mathcal M)`` | volume of manifold ``\mathcal M`` | |
+| ``\theta_p(X)`` | volume density for vector ``X`` tangent at point ``p`` | |
 | ``0_k`` | the ``k\times k`` zero matrix. | |
diff --git a/src/Manifolds.jl b/src/Manifolds.jl
@@ -319,6 +319,7 @@ using Random
 using RecursiveArrayTools: ArrayPartition
 using Requires
 using SimpleWeightedGraphs: AbstractSimpleWeightedGraph, get_weight
+using SpecialFunctions
 using StaticArrays
 using Statistics
 using StatsBase
@@ -487,6 +488,37 @@ function Base.in(X, TpM::TangentSpaceAtPoint; kwargs...)
     return is_vector(base_manifold(TpM), TpM.point, X, false; kwargs...)
 end
 
+@doc raw"""
+    manifold_volume(M::AbstractManifold)
+
+Volume of manifold `M` defined through integration of Riemannian volume element in a chart.
+Note that for many manifolds there is no universal agreement over the exact ranges over
+which the integration should happen. For details see [^BoyaSudarshanTilma2003].
+
+[^BoyaSudarshanTilma2003]:
+    > L. J. Boya, E. C. G. Sudarshan, and T. Tilma, “Volumes of Compact Manifolds,” Reports
+    > on Mathematical Physics, vol. 52, no. 3, pp. 401–422, Dec. 2003,
+    > doi: [10.1016/S0034-4877(03)80038-1](https://doi.org/10.1016/S0034-4877(03)80038-1)
+"""
+manifold_volume(::AbstractManifold)
+
+@doc raw"""
+    volume_density(M::AbstractManifold, p, X)
+
+Volume density function of manifold `M`, i.e. determinant of the differential of exponential map
+`exp(M, p, X)`. Determinant can be understood as computed in a basis, from the matrix
+of the linear operator said differential corresponds to. Details are available in Section 4.1
+of [^ChevallierLiLuDunson2022].
+
+Note that volume density is well-defined only for `X` for which `exp(M, p, X)` is injective.
+
+[^ChevallierLiLuDunson2022]:
+    > E. Chevallier, D. Li, Y. Lu, and D. B. Dunson, “Exponential-wrapped distributions on
+    > symmetric spaces.” arXiv, Oct. 09, 2022.
+    > doi: [10.48550/arXiv.2009.01983](https://doi.org/10.48550/arXiv.2009.01983).
+"""
+volume_density(::AbstractManifold, p, X)
+
 # functions populated with methods by extensions
 
 function solve_chart_log_bvp end
@@ -789,6 +821,7 @@ export ×,
     log!,
     log_local_metric_density,
     manifold_dimension,
+    manifold_volume,
     metric,
     mean,
     mean!,
@@ -852,6 +885,7 @@ export ×,
     vee!,
     vertical_component,
     vertical_component!,
+    volume_density,
     zero_vector,
     zero_vector!
 # Lie group types & functions

diff --git a/src/groups/general_unitary_groups.jl b/src/groups/general_unitary_groups.jl
@@ -279,6 +279,10 @@ function log_lie!(
     return project!(G, X, Identity(G), X)
 end
 
+function manifold_volume(M::GeneralUnitaryMultiplicationGroup)
+    return manifold_volume(M.manifold)
+end
+
 function Random.rand!(G::GeneralUnitaryMultiplicationGroup, pX; kwargs...)
     rand!(G.manifold, pX; kwargs...)
     return pX
@@ -328,3 +332,7 @@ function translate_diff!(
 )
     return copyto!(G, Y, inv(G, p) * X * p)
 end
+
+function volume_density(M::GeneralUnitaryMultiplicationGroup, p, X)
+    return volume_density(M.manifold, p, X)
+end
diff --git a/src/manifolds/Circle.jl b/src/manifolds/Circle.jl
@@ -331,6 +331,13 @@ i.e. $\dim(𝕊^1) = 1$.
 """
 manifold_dimension(::Circle) = 1
 
+@doc raw"""
+    manifold_volume(M::Circle)
+
+Return the volume of the [`Circle`](@ref) `M`, i.e. ``2π``.
+"""
+manifold_volume(::Circle) = 2 * π
+
 @doc raw"""
     mean(M::Circle{ℝ}, x::AbstractVector[, w::AbstractWeights])
 
@@ -525,5 +532,12 @@ function parallel_transport_to!(M::Circle{ℂ}, Y, p, X, q)
     return Y
 end
 
+"""
+    volume_density(::Circle, p, X)
+
+Return volume density of [`Circle`](@ref), i.e. 1.
+"""
+volume_density(::Circle, p, X) = one(eltype(X))
+
 zero_vector(::Circle, p::T) where {T<:Number} = zero(p)
 zero_vector!(::Circle, X, p) = fill!(X, 0)
diff --git a/src/manifolds/Euclidean.jl b/src/manifolds/Euclidean.jl
@@ -454,6 +454,13 @@ function manifold_dimension(M::Euclidean{N,𝔽}) where {N,𝔽}
 end
 manifold_dimension(::Euclidean{Tuple{},𝔽}) where {𝔽} = real_dimension(𝔽)
 
+"""
+    manifold_volume(::Euclidean)
+
+Return volume of the [`Euclidean`](@ref) manifold, i.e. infinity.
+"""
+manifold_volume(::Euclidean) = Inf
+
 Statistics.mean(::Euclidean{Tuple{}}, x::AbstractVector{<:Number}; kwargs...) = mean(x)
 function Statistics.mean(
     ::Euclidean{Tuple{}},
@@ -709,6 +716,15 @@ function Statistics.var(::Euclidean, x::AbstractVector{<:Number}, m::Number; kwa
     return sum(var(x; mean=m, kwargs...))
 end
 
+@doc raw"""
+    volume_density(M::Euclidean, p, X)
+
+Return volume density function of [`Euclidean`](@ref) manifold `M`, i.e. 1.
+"""
+function volume_density(::Euclidean, p, X)
+    return one(eltype(X))
+end
+
 """
     zero_vector(M::Euclidean, x)