Introduce AbstractApproximationMethod

NEWS.md

@@ -5,6 +5,13 @@ 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.15.6] unreleased
+
+### Added
+
+* An `AbstractApproximationMethod` to specify estimation methods for other more general functions,
+as well as a `default_estimation_method` to specify defaults on manifolds.
+
 ## [0.15.5] 13/12/2023
 
 ### Added

Project.toml

@@ -1,7 +1,7 @@
 name = "ManifoldsBase"
 uuid = "3362f125-f0bb-47a3-aa74-596ffd7ef2fb"
 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.15.5"
+version = "0.15.6"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

docs/make.jl

@@ -2,6 +2,26 @@
 #
 #
 
+if "--help" ∈ ARGS
+    println(
+        """
+docs/make.jl
+
+Render the `Manopt.jl` documenation with optinal arguments
+
+Arguments
+* `--help`              - print this help and exit without rendering the documentation
+* `--prettyurls`        – toggle the prettyurls part to true (which is otherwise only true on CI)
+* `--quarto`            – run the Quarto notebooks from the `tutorials/` folder before generating the documentation
+  this has to be run locally at least once for the `tutorials/*.md` files to exist that are included in
+  the documentation (see `--exclude-tutorials`) for the alternative.
+  If they are generated ones they are cached accordingly.
+  Then you can spare time in the rendering by not passing this argument.
+""",
+    )
+    exit(0)
+end
+
 #
 # (a) if docs is not the current active environment, switch to it
 # (from https://github.com/JuliaIO/HDF5.jl/pull/1020/) 
@@ -30,18 +50,19 @@ if "--quarto" ∈ ARGS
     end
 end
 
-using Documenter: DocMeta, HTML, MathJax3, deploydocs, makedocs
+using Documenter
 using DocumenterCitations
 using ManifoldsBase
 
 # (e) ...finally! make docs
 bib = CitationBibliography(joinpath(@__DIR__, "src", "references.bib"); style = :alpha)
 makedocs(;
     # for development, we disable prettyurls
-    format = HTML(;
-        mathengine = MathJax3(),
-        prettyurls = get(ENV, "CI", nothing) == "true",
-        assets = ["assets/favicon.ico"],
+    format = Documenter.HTML(;
+        prettyurls = (get(ENV, "CI", nothing) == "true") || ("--prettyurls" ∈ ARGS),
+        assets = ["assets/favicon.ico", "assets/citations.css"],
+        size_threshold_warn = 200 * 2^10, # raise slightly from 100 to 200 KiB
+        size_threshold = 300 * 2^10,      # raise slightly 200 to to 300 KiB
     ),
     modules = [ManifoldsBase],
     authors = "Seth Axen, Mateusz Baran, Ronny Bergmann, and contributors.",

docs/src/functions.md

@@ -58,6 +58,14 @@ Public=false
 Private=true
 ```
 
+## Approximation Methods
+
+```@autodocs
+Modules = [ManifoldsBase]
+Pages = ["approximation_methods.jl"]
+Order = [:type, :function]
+```
+
 ## Error Messages
 
 This interface introduces a small set of own error messages.

src/ManifoldsBase.jl

@@ -29,6 +29,7 @@ include("maintypes.jl")
 include("numbers.jl")
 include("Fiber.jl")
 include("bases.jl")
+include("approximation_methods.jl")
 include("retractions.jl")
 include("exp_log_geo.jl")
 include("projections.jl")
@@ -1016,6 +1017,17 @@ export AbstractPowerRepresentation,
     NestedPowerRepresentation, NestedReplacingPowerRepresentation
 export ProductManifold
 
+# (b) Generic Estimation Types
+
+export GeodesicInterpolationWithinRadius,
+    CyclicProximalPointEstimation,
+    ExtrinsicEstimation,
+    GradientDescentEstimation,
+    WeiszfeldEstimation,
+    AbstractApproximationMethod,
+    GeodesicInterpolation
+
+
 # (b) Retraction Types
 export AbstractRetractionMethod,
     ApproximateInverseRetraction,
@@ -1093,6 +1105,7 @@ export ×,
     change_representer!,
     copy,
     copyto!,
+    default_estimation_method,
     default_inverse_retraction_method,
     default_retraction_method,
     default_vector_transport_method,

src/approximation_methods.jl

@@ -0,0 +1,93 @@
+@doc raw"""
+    AbstractApproximationMethod
+
+Abstract type for defining estimation methods on manifolds.
+"""
+abstract type AbstractApproximationMethod end
+
+@doc raw"""
+    GradientDescentEstimation <: AbstractApproximationMethod
+
+Method for estimation using [📖 gradient descent](https://en.wikipedia.org/wiki/Gradient_descent).
+"""
+struct GradientDescentEstimation <: AbstractApproximationMethod end
+
+@doc raw"""
+    CyclicProximalPointEstimation <: AbstractApproximationMethod
+
+Method for estimation using the cyclic proximal point technique, which is based on [📖 proximal maps](https://en.wikipedia.org/wiki/Proximal_operator).
+"""
+struct CyclicProximalPointEstimation <: AbstractApproximationMethod end
+
+@doc raw"""
+    EfficientEstimator <: AbstractApproximationMethod
+
+Method for estimation in the best possible sense, see [📖 Efficiency (Statictsics)](https://en.wikipedia.org/wiki/Efficiency_(statistics)) for mroe details.
+This can for example be used when computing the usual mean on an Euclidean space, which is the best estimator.
+"""
+struct EfficientEstimator <: AbstractApproximationMethod end
+
+
+@doc raw"""
+    ExtrinsicEstimation{T} <: AbstractApproximationMethod
+
+Method for estimation in the ambient space with a method of type `T` and projecting the result back
+to the manifold.
+"""
+struct ExtrinsicEstimation{T} <: AbstractApproximationMethod
+    extrinsic_estimation::T
+end
+
+@doc raw"""
+    WeiszfeldEstimation <: AbstractApproximationMethod
+
+Method for estimation using the Weiszfeld algorithm, compare for example the computation of the
+[📖 Geometric median](https://en.wikipedia.org/wiki/Geometric_median).
+"""
+struct WeiszfeldEstimation <: AbstractApproximationMethod end
+
+@doc raw"""
+    GeodesicInterpolation <: AbstractApproximationMethod
+
+Method for estimation based on geodesic interpolation.
+"""
+struct GeodesicInterpolation <: AbstractApproximationMethod end
+
+@doc raw"""
+    GeodesicInterpolationWithinRadius{T} <: AbstractApproximationMethod
+
+Method for estimation based on geodesic interpolation that is restricted to some `radius`
+
+# Constructor
+
+    GeodesicInterpolationWithinRadius(radius)
+"""
+struct GeodesicInterpolationWithinRadius{T} <: AbstractApproximationMethod
+    radius::T
+    function GeodesicInterpolationWithinRadius(radius::T) where {T}
+        radius > 0 && return new{T}(radius)
+        return throw(
+            DomainError("The radius must be strictly postive, received $(radius)."),
+        )
+    end
+end
+
+@doc raw"""
+    default_estimation_method(M::AbstractManifold)
+    default_estimation_method(M::AbtractManifold, f, T)
+
+Specify a default estimation method for an [`AbstractManifold`](@ref) and (optional)
+for a specific function `f` and a type `T` to distinguish different (point or vector)
+representations on M.
+
+By default, all functions `f` call the signature for just a manifold.
+The exceptional functions are
+
+* `retract` and `retract!` which fall back to [`default_retraction_method`](@ref)
+* `inverse_retract` and `inverse_retract!` which fall back to [`default_inverse_retraction_method`](@ref)
+* any of the vector transport mehods fall back to [`default_vector_transport_method`](@ref)
+"""
+default_estimation_method(M::AbstractManifold)
+
+default_estimation_method(M::AbstractManifold, f, T) = default_estimation_method(M, f)
+default_estimation_method(M::AbstractManifold, f) = default_estimation_method(M)

src/retractions.jl

@@ -1,16 +1,16 @@
 """
-    AbstractInverseRetractionMethod
+    AbstractInverseRetractionMethod <: AbstractApproximationMethod
 
 Abstract type for methods for inverting a retraction (see [`inverse_retract`](@ref)).
 """
-abstract type AbstractInverseRetractionMethod end
+abstract type AbstractInverseRetractionMethod <: AbstractApproximationMethod end
 
 """
-    AbstractRetractionMethod
+    AbstractRetractionMethod <: AbstractApproximationMethod
 
 Abstract type for methods for [`retract`](@ref)ing a tangent vector to a manifold.
 """
-abstract type AbstractRetractionMethod end
+abstract type AbstractRetractionMethod <: AbstractApproximationMethod end
 
 """
     ApproximateInverseRetraction <: AbstractInverseRetractionMethod
@@ -934,3 +934,30 @@ function retract_sasaki! end
 
 Base.show(io::IO, ::CayleyRetraction) = print(io, "CayleyRetraction()")
 Base.show(io::IO, ::PadeRetraction{m}) where {m} = print(io, "PadeRetraction($m)")
+
+#
+# default estimation methods pass down with and without the point type
+function default_estimation_method(M::AbstractManifold, ::typeof(inverse_retract))
+    return default_inverse_retraction_method(M)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(inverse_retract), T)
+    return default_inverse_retraction_method(M, T)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(inverse_retract!))
+    return default_inverse_retraction_method(M)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(inverse_retract!), T)
+    return default_inverse_retraction_method(M, T)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(retract))
+    return default_retraction_method(M)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(retract), T)
+    return default_retraction_method(M, T)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(retract!))
+    return default_retraction_method(M)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(retract!), T)
+    return default_retraction_method(M, T)
+end

src/vector_transport.jl

@@ -1,6 +1,6 @@
 
 """
-    AbstractVectorTransportMethod
+    AbstractVectorTransportMethod <: AbstractApproximationMethod
 
 Abstract type for methods for transporting vectors. Such vector transports are not
 necessarily linear.
@@ -9,7 +9,7 @@ necessarily linear.
 
 [`AbstractLinearVectorTransportMethod`](@ref)
 """
-abstract type AbstractVectorTransportMethod end
+abstract type AbstractVectorTransportMethod <: AbstractApproximationMethod end
 
 """
     AbstractLinearVectorTransportMethod <: AbstractVectorTransportMethod
@@ -310,6 +310,7 @@ function default_vector_transport_method(M::AbstractManifold, ::Type{T}) where {
     return default_vector_transport_method(M)
 end
 
+
 @doc raw"""
     pole_ladder(
         M,
@@ -1357,3 +1358,59 @@ function _vector_transport_to!(
         m.inverse_retraction,
     )
 end
+
+# default estimation fallbacks with and without the T
+function default_estimation_method(
+    M::AbstractManifold,
+    ::typeof(vector_transport_direction),
+)
+    return default_vector_transport_method(M)
+end
+function default_estimation_method(
+    M::AbstractManifold,
+    ::typeof(vector_transport_direction!),
+)
+    return default_vector_transport_method(M)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(vector_transport_along))
+    return default_vector_transport_method(M)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(vector_transport_to))
+    return default_vector_transport_method(M)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(vector_transport_along!))
+    return default_vector_transport_method(M)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(vector_transport_to!))
+    return default_vector_transport_method(M)
+end
+function default_estimation_method(
+    M::AbstractManifold,
+    ::typeof(vector_transport_direction),
+    T,
+)
+    return default_vector_transport_method(M, T)
+end
+function default_estimation_method(
+    M::AbstractManifold,
+    ::typeof(vector_transport_direction!),
+    T,
+)
+    return default_vector_transport_method(M, T)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(vector_transport_along), T)
+    return default_vector_transport_method(M, T)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(vector_transport_to), T)
+    return default_vector_transport_method(M, T)
+end
+function default_estimation_method(
+    M::AbstractManifold,
+    ::typeof(vector_transport_along!),
+    T,
+)
+    return default_vector_transport_method(M, T)
+end
+function default_estimation_method(M::AbstractManifold, ::typeof(vector_transport_to!), T)
+    return default_vector_transport_method(M, T)
+end