Merge branch 'master' into alloc2

Author: kellertuer

Changelog.md

@@ -6,10 +6,23 @@ The file was started with Version `0.4`.
 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.5.22] September 09, 2025
+
+### Added
+
+* a `keywords_accepted(f, mode=:warn; kwargs...)` function that verifies that all keywords are accepted by a certain function.
+* an internal function `calls_with_kwargs(f)` to indicate which functions `f` passes `kwargs...` to.
+* a `KeywordsErrorMode` preference parameter to control how keywords that are not used/allowed should be treated. Values are `"none"`, `"warn"` (default), and `"error"`.
+* Add Distance over Gradients (RDoG) stepsize: `DistanceOverGradientsStepsize` and factory `DistanceOverGradients`, a learning‑rate‑free, curvature‑aware stepsize with `show`/`repr` and tests on Euclidean, Sphere, and Hyperbolic manifolds.
+
+### Fixed
+* the typo in the name `AdaptiveRgularizationWithCubicsModelObjective` is fixed to `AdaptiveRegularizationWithCubicsModelObjective`.
+
 ## [0.5.21] September 5, 2025
 
 ### Added
 
+* a system to track keywords, warning when unused ones are passed and a static way to explore possible keywords.
 * a `warm_start_factor` field to `ProximalGradientMethodBacktrackingStepsize` to allow to scale the stepsize in the backtracking procedure.
 * a `gradient=` keyword in several `Stepsize`s, such that one can avoid to internally avoid computing the gradient again.
 * used the ``gradient=` keyword in

Project.toml

@@ -1,7 +1,7 @@
 name = "Manopt"
 uuid = "0fc0a36d-df90-57f3-8f93-d78a9fc72bb5"
 authors = ["Ronny Bergmann <manopt@ronnybergmann.net>"]
-version = "0.5.21"
+version = "0.5.22"
 
 [deps]
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"

docs/src/plans/index.md

@@ -58,11 +58,30 @@ You can further activate a “Tutorial” mode by `set_parameter!(:Mode, "Tutori
 Manopt.is_tutorial_mode
 ```
 
-# A factory for providing manifold defaults
+## A factory for providing manifold defaults
 
 In several cases a manifold might not yet be known at the time a (keyword) argument should be provided. Therefore, any type with a manifold default can be wrapped into a factory.
 
 ```@docs
 Manopt.ManifoldDefaultsFactory
 Manopt._produce_type
+```
+
+## Keyword arguments and their verification
+
+Internally `Manopt.jl` passes keywords for the (high-level) solver
+functions to several inner functions, e.g. to add debug or caching.
+Besides the documentation, one can check with the internal function [`Manopt.accepted_keywords`](@ref) which keywords a solver accepts.
+
+A solver also warns, if a keyword is passed, that is not handled by the
+solver or any of the inner functions it calls.
+
+```@docs
+Manopt.Keywords
+Manopt.accepted_keywords
+Manopt.ManoptKeywordError
+Manopt.add!
+Manopt.calls_with_kwargs
+Manopt.direct_keywords
+Manopt.keywords_accepted
 ```

docs/src/plans/stepsize.md

@@ -24,6 +24,7 @@ AdaptiveWNGradient
 ArmijoLinesearch
 ConstantLength
 DecreasingLength
+DistanceOverGradients
 NonmonotoneLinesearch
 Polyak
 WolfePowellLinesearch
@@ -45,7 +46,7 @@ Modules = [Manopt]
 Pages = ["plans/stepsize.jl"]
 Private = true
 Order = [:function, :type]
-Filter = t -> !(t in [Stepsize, AdaptiveWNGradient, ArmijoLinesearch, ConstantLength, DecreasingLength, NonmonotoneLinesearch, Polyak, WolfePowellLinesearch, WolfePowellBinaryLinesearch ])
+Filter = t -> !(t in [Stepsize, AdaptiveWNGradient, ArmijoLinesearch, ConstantLength, DecreasingLength, DistanceOverGradients, NonmonotoneLinesearch, Polyak, WolfePowellLinesearch, WolfePowellBinaryLinesearch ])
 ```
 
 

docs/src/references.bib

@@ -5,6 +5,7 @@
 % --- A
 %
 %
+
 @book{AbsilMahonySepulchre:2008,
     AUTHOR    = {Absil, P.-A. and Mahony, R. and Sepulchre, R.},
     DOI       = {10.1515/9781400830244},
@@ -287,6 +288,7 @@ @techreport{deCasteljau:1963
     YEAR      = {1963}
 }
 
+
 @article{ChambollePock:2011,
     AUTHOR       = {Chambolle, Antonin and Pock, Thomas},
     YEAR         = {2011},
@@ -337,6 +339,7 @@ @article{DaiYuan:1999
     VOLUME    = {10},
     YEAR      = {1999}
 }
+
 @article{DiepeveenLellmann:2021,
     AUTHOR     = {Willem Diepeveen and Jan Lellmann},
     DOI        = {10.1137/21m1398513},
@@ -351,13 +354,22 @@ @article{DiepeveenLellmann:2021
     VOLUME     = {14},
     YEAR       = {2021},
 }
+
+@article{DoddSharrockNemeth:2024,
+  title={Learning-rate-free stochastic optimization over Riemannian manifolds},
+  author={Dodd, Daniel and Sharrock, Louis and Nemeth, Christopher},
+  journal={arXiv preprint arXiv:2406.02296},
+  year={2024}
+}
+
 @techreport{Dreisigmeyer:2007,
     AUTHOR = {Dreisigmeyer, David W.},
     INSTITUTION = {Optimization Online},
     TITLE = {Direct Search Alogirthms over Riemannian Manifolds},
     URL = {https://optimization-online.org/?p=9134},
     YEAR = {2007}
 }
+
 @article{DuranMoelleSbertCremers:2016,
     AUTHOR   = {Duran, J. and Moeller, M. and Sbert, C. and Cremers, D.},
     TITLE    = {Collaborative Total Variation: A General Framework for Vectorial TV Models},

docs/src/solvers/adaptive-regularization-with-cubics.md

@@ -32,13 +32,13 @@ Manopt.LanczosState
 There is a generic objective, that implements the sub problem
 
 ```@docs
-AdaptiveRagularizationWithCubicsModelObjective
+AdaptiveRegularizationWithCubicsModelObjective
 ```
 
 Since the sub problem is given on the tangent space, you have to provide
 
 ```
-arc_obj = AdaptiveRagularizationWithCubicsModelObjective(mho, σ)
+arc_obj = AdaptiveRegularizationWithCubicsModelObjective(mho, σ)
 sub_problem = DefaultProblem(TangentSpaceAt(M,p), arc_obj)
 ```
 

ext/ManoptRecursiveArrayToolsExt.jl

@@ -80,6 +80,7 @@ end
 function alternating_gradient_descent(
         M::ProductManifold, ago::ManifoldAlternatingGradientObjective, p; kwargs...
     )
+    Manopt.keywords_accepted(alternating_gradient_descent; kwargs...)
     q = copy(M, p)
     return alternating_gradient_descent!(M, ago, q; kwargs...)
 end
@@ -110,6 +111,7 @@ function alternating_gradient_descent!(
         retraction_method::AbstractRetractionMethod = default_retraction_method(M, typeof(p)),
         kwargs...,
     )
+    Manopt.keywords_accepted(alternating_gradient_descent!; kwargs...)
     dagmo = Manopt.decorate_objective!(M, agmo; kwargs...)
     dmp = DefaultManoptProblem(M, dagmo)
     agds = AlternatingGradientDescentState(

src/Manopt.jl

@@ -194,7 +194,7 @@ include("solvers/conjugate_gradient_descent.jl")
 include("solvers/conjugate_residual.jl")
 include("solvers/cyclic_proximal_point.jl")
 include("solvers/difference_of_convex_algorithm.jl")
-include("solvers/difference-of-convex-proximal-point.jl")
+include("solvers/difference_of_convex_proximal_point.jl")
 include("solvers/DouglasRachford.jl")
 include("solvers/exact_penalty_method.jl")
 include("solvers/projected_gradient_method.jl")
@@ -448,6 +448,7 @@ export NeverRestart, RestartOnNonDescent, RestartOnNonSufficientDescent
 #
 # Solvers
 export adaptive_regularization_with_cubics,
+    accepted_keywords,
     adaptive_regularization_with_cubics!,
     alternating_gradient_descent,
     alternating_gradient_descent!,
@@ -516,13 +517,14 @@ export solve!
 export ApproxHessianFiniteDifference, ApproxHessianSymmetricRankOne, ApproxHessianBFGS
 export update_hessian!, update_hessian_basis!
 export ExactPenaltyCost, ExactPenaltyGrad, AugmentedLagrangianCost, AugmentedLagrangianGrad
-export AdaptiveRagularizationWithCubicsModelObjective
+export AdaptiveRegularizationWithCubicsModelObjective
 export ExactPenaltyCost, ExactPenaltyGrad
 export SmoothingTechnique, LinearQuadraticHuber, LogarithmicSumOfExponentials
 #
 # Stepsize
 export Stepsize
-export AdaptiveWNGradient, ConstantLength, DecreasingLength, Polyak
+export AdaptiveWNGradient, ConstantLength, DecreasingLength,
+    Polyak, DistanceOverGradients, DistanceOverGradientsStepsize
 export ProximalGradientMethodBacktracking
 export ArmijoLinesearch, Linesearch, NonmonotoneLinesearch
 export get_stepsize, get_initial_stepsize, get_last_stepsize

src/documentation_glossary.jl

@@ -65,6 +65,8 @@ define!(:LaTeX, :bar, (letter) -> raw"\bar" * "$(letter)")
 define!(:LaTeX, :big, raw"\big")
 define!(:LaTeX, :bigl, raw"\bigl")
 define!(:LaTeX, :bigr, raw"\bigr")
+define!(:LaTeX, :biggl, raw"\biggl")
+define!(:LaTeX, :biggr, raw"\biggr")
 define!(:LaTeX, :Big, raw"\Big")
 define!(:LaTeX, :Bigl, raw"\Bigl")
 define!(:LaTeX, :Bigr, raw"\Bigr")

…btive_regularization_with_cubics_plan.jl …ptive_regularization_with_cubics_plan.jlsrc/plans/adabtive_regularization_with_cubics_plan.jl renamed to src/plans/adaptive_regularization_with_cubics_plan.jl src/plans/adabtive_regularization_with_cubics_plan.jl renamed to src/plans/adaptive_regularization_with_cubics_plan.jl

@@ -1,5 +1,5 @@
 @doc """
-    AdaptiveRagularizationWithCubicsModelObjective
+    AdaptiveRegularizationWithCubicsModelObjective
 
 A model for the adaptive regularization with Cubics
 
@@ -17,40 +17,40 @@ cf. Eq. (33) in [AgarwalBoumalBullinsCartis:2020](@cite)
 
 # Constructors
 
-    AdaptiveRagularizationWithCubicsModelObjective(mho, σ=1.0)
+    AdaptiveRegularizationWithCubicsModelObjective(mho, σ=1.0)
 
 with either an [`AbstractManifoldHessianObjective`](@ref) `objective` or an decorator containing such an objective.
 """
-mutable struct AdaptiveRagularizationWithCubicsModelObjective{
+mutable struct AdaptiveRegularizationWithCubicsModelObjective{
         E <: AbstractEvaluationType,
         O <: Union{ManifoldHessianObjective, AbstractDecoratedManifoldObjective},
         R,
     } <: AbstractManifoldSubObjective{E, O}
     objective::O
     σ::R
 end
-function AdaptiveRagularizationWithCubicsModelObjective(
+function AdaptiveRegularizationWithCubicsModelObjective(
         mho::O, σ::R = 1.0
     ) where {
         E, O <: Union{AbstractManifoldHessianObjective{E}, AbstractDecoratedManifoldObjective{E}}, R,
     }
-    return AdaptiveRagularizationWithCubicsModelObjective{E, O, R}(mho, σ)
+    return AdaptiveRegularizationWithCubicsModelObjective{E, O, R}(mho, σ)
 end
 function set_parameter!(
-        f::AdaptiveRagularizationWithCubicsModelObjective,
+        f::AdaptiveRegularizationWithCubicsModelObjective,
         ::Union{Val{:σ}, Val{:RegularizationParameter}},
         σ,
     )
     f.σ = σ
     return f
 end
 
-get_objective(arcmo::AdaptiveRagularizationWithCubicsModelObjective) = arcmo.objective
+get_objective(arcmo::AdaptiveRegularizationWithCubicsModelObjective) = arcmo.objective
 
 @doc """
-    get_cost(TpM, trmo::AdaptiveRagularizationWithCubicsModelObjective, X)
+    get_cost(TpM, trmo::AdaptiveRegularizationWithCubicsModelObjective, X)
 
-Evaluate the tangent space [`AdaptiveRagularizationWithCubicsModelObjective`](@ref)
+Evaluate the tangent space [`AdaptiveRegularizationWithCubicsModelObjective`](@ref)
 
 ```math
 m(X) = f(p) + ⟨$(_tex(:grad)) f(p), X ⟩_p + $(_tex(:frac, "1", "2")) ⟨$(_tex(:Hess)) f(p)[X], X⟩_p
@@ -60,7 +60,7 @@ m(X) = f(p) + ⟨$(_tex(:grad)) f(p), X ⟩_p + $(_tex(:frac, "1", "2")) ⟨$(_t
 at `X`, cf. Eq. (33) in [AgarwalBoumalBullinsCartis:2020](@cite).
 """
 function get_cost(
-        TpM::TangentSpace, arcmo::AdaptiveRagularizationWithCubicsModelObjective, X
+        TpM::TangentSpace, arcmo::AdaptiveRegularizationWithCubicsModelObjective, X
     )
     M = base_manifold(TpM)
     p = TpM.point
@@ -69,13 +69,13 @@ function get_cost(
     Y = get_objective_hessian(M, arcmo, p, X)
     return c + inner(M, p, G, X) + 1 / 2 * inner(M, p, Y, X) + arcmo.σ / 3 * norm(M, p, X)^3
 end
-function get_cost_function(arcmo::AdaptiveRagularizationWithCubicsModelObjective)
+function get_cost_function(arcmo::AdaptiveRegularizationWithCubicsModelObjective)
     return (TpM, X) -> get_cost(TpM, arcmo, X)
 end
 @doc """
-    get_gradient(TpM, trmo::AdaptiveRagularizationWithCubicsModelObjective, X)
+    get_gradient(TpM, trmo::AdaptiveRegularizationWithCubicsModelObjective, X)
 
-Evaluate the gradient of the [`AdaptiveRagularizationWithCubicsModelObjective`](@ref)
+Evaluate the gradient of the [`AdaptiveRegularizationWithCubicsModelObjective`](@ref)
 
 ```math
 $(_tex(:grad)) m(X) = $(_tex(:grad)) f(p) + $(_tex(:Hess)) f(p)[X]
@@ -85,22 +85,22 @@ $(_tex(:grad)) m(X) = $(_tex(:grad)) f(p) + $(_tex(:Hess)) f(p)[X]
 at `X`, cf. Eq. (37) in [AgarwalBoumalBullinsCartis:2020](@cite).
 """
 function get_gradient(
-        TpM::TangentSpace, arcmo::AdaptiveRagularizationWithCubicsModelObjective, X
+        TpM::TangentSpace, arcmo::AdaptiveRegularizationWithCubicsModelObjective, X
     )
     M = base_manifold(TpM)
     p = TpM.point
     G = get_objective_gradient(M, arcmo, p)
     return G + get_objective_hessian(M, arcmo, p, X) + arcmo.σ * norm(M, p, X) * X
 end
 function get_gradient!(
-        TpM::TangentSpace, Y, arcmo::AdaptiveRagularizationWithCubicsModelObjective, X
+        TpM::TangentSpace, Y, arcmo::AdaptiveRegularizationWithCubicsModelObjective, X
     )
     M = base_manifold(TpM)
     p = TpM.point
     get_objective_hessian!(M, Y, arcmo, p, X)
     Y .= Y + get_objective_gradient(M, arcmo, p) + arcmo.σ * norm(M, p, X) * X
     return Y
 end
-function get_gradient_function(arcmo::AdaptiveRagularizationWithCubicsModelObjective)
+function get_gradient_function(arcmo::AdaptiveRegularizationWithCubicsModelObjective)
     return (TpM, X) -> get_gradient(TpM, arcmo, X)
 end