An idea to provide Hints and Errors on Keywords (#503)

* First few steps towards handling Keywords.
* Start a first list.
* export keywords_accepted as an interface function.
* Simplify `origins` to always be a vector.
* Bump version number.

---------

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

Author: kellertuer

Changelog.md

@@ -6,16 +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).
 
-## [candidate] September 8, 2025
+## [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/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")
@@ -481,6 +481,7 @@ export adaptive_regularization_with_cubics,
     gradient_descent!,
     interior_point_Newton,
     interior_point_Newton!,
+    keywords_accepted,
     LevenbergMarquardt,
     LevenbergMarquardt!,
     mesh_adaptive_direct_search,
@@ -516,7 +517,7 @@ 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
 #

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

src/plans/augmented_lagrangian_plan.jl

@@ -1,12 +1,14 @@
 _doc_AL_Cost(iter) = "$(_tex(:Cal, "L"))_{ρ^{($iter)}}(p, μ^{($iter)}, λ^{($iter)})"
-_doc_AL_Cost_long = raw"""
+_doc_AL_Cost_long = """
 ```math
-\mathcal L_\rho(p, μ, λ)
-= f(x) + $(_tex(:frac, "ρ", "2")) \biggl(
-    \sum_{j=1}^n \Bigl( h_j(p) + $(_tex(:frac, "λ_j", "ρ")) \Bigr)^2
-    +
-    \sum_{i=1}^m \max\Bigl\{ 0, $(_tex(:frac, "μ_i", "ρ} + g_i(p) \Bigr\"))^2
-\Bigr)
+$(_tex(:Cal, "L"))_ρ(p, μ, λ)
+= f(x) + $(_tex(:frac, "ρ", "2"))$(_tex(:biggl))(
+  $(_tex(:sum, "j=1", "n"))$(_tex(:Bigl))(
+    h_j(p) + $(_tex(:frac, "λ_j", "ρ"))
+  $(_tex(:Bigr)))^2
+  +
+  $(_tex(:sum, "i=1", "m"))$(_tex(:max))$(_tex(:set, "0, $(_tex(:frac, "μ_i", "ρ")) + g_i(p)"))^2
+$(_tex(:biggr)))
 ```
 """