From 318bca30e6553b0a778d01c8672fdea07b1e830c Mon Sep 17 00:00:00 2001 From: Ronny Bergmann Date: Tue, 27 Aug 2024 09:27:34 +0200 Subject: [PATCH] Unify signatures, fix a few tex typos and improve english on the factory info/note. --- src/documentation_glossary.jl | 6 ++-- src/plans/conjugate_gradient_plan.jl | 2 +- src/plans/gradient_plan.jl | 4 +-- src/plans/stepsize.jl | 35 +++++++++++---------- src/solvers/DouglasRachford.jl | 2 +- src/solvers/NelderMead.jl | 2 +- src/solvers/alternating_gradient_descent.jl | 2 +- src/solvers/gradient_descent.jl | 2 +- src/solvers/stochastic_gradient_descent.jl | 2 +- 9 files changed, 28 insertions(+), 29 deletions(-) diff --git a/src/documentation_glossary.jl b/src/documentation_glossary.jl index f0f7626539..b30b25f268 100644 --- a/src/documentation_glossary.jl +++ b/src/documentation_glossary.jl @@ -176,10 +176,8 @@ define!( (type::String) -> """ !!! info This function generates a [`ManifoldDefaultsFactory`](@ref) for [`$(type)`](@ref). - If you do not provide a manifold, the manifold `M` later provided to (usually) generate - the corresponding [`AbstractManoptSolverState`](@ref) will be used. - This affects all arguments and keyword argumentss with defaults that depend on the manifold, - unless provided with a value here. + For default values, that depend on the manifold, this factory postpones the construction + until the manifold from for example a corresponding [`AbstractManoptSolverState`](@ref) is available. """, ) define!( diff --git a/src/plans/conjugate_gradient_plan.jl b/src/plans/conjugate_gradient_plan.jl index f1506dd782..859d3a87f4 100644 --- a/src/plans/conjugate_gradient_plan.jl +++ b/src/plans/conjugate_gradient_plan.jl @@ -39,7 +39,7 @@ $(_var(:Field, :vector_transport_method)) # Constructor - ConjugateGradientState(M; kwargs...) + ConjugateGradientState(M::AbstractManifold; kwargs...) where the last five fields can be set by their names as keyword and the `X` can be set to a tangent vector type using the keyword `initial_gradient` which defaults to `zero_vector(M,p)`, diff --git a/src/plans/gradient_plan.jl b/src/plans/gradient_plan.jl index 86bff3dab5..f31cc0665d 100644 --- a/src/plans/gradient_plan.jl +++ b/src/plans/gradient_plan.jl @@ -448,8 +448,8 @@ function (a::AverageGradientRule)( end """ - AverageGradient(M; kwargs...) AverageGradient(; kwargs...) + AverageGradient(M::AbstractManifold; kwargs...) Add an average of gradients to a gradient processor. A set of previous directions (from the inner processor) and the last iterate are stored, average is taken after vector transporting @@ -548,7 +548,7 @@ end @doc """ Nesterov(; kwargs...) - Nesterov(M; kwargs...) + Nesterov(M::AbstractManifold; kwargs...) Assume ``f`` is ``L``-Lipschitz and ``μ``-strongly convex. Given diff --git a/src/plans/stepsize.jl b/src/plans/stepsize.jl index 26264ab5b8..5bc5614e98 100644 --- a/src/plans/stepsize.jl +++ b/src/plans/stepsize.jl @@ -95,7 +95,7 @@ end ConstantLength(s; kwargs...) ConstantLength(M::AbstractManifold, s; kwargs...) -Specify a [`Stepsize`] that is constant. +Specify a [`Stepsize`](@ref) that is constant. # Input @@ -191,8 +191,8 @@ function show(io::IO, s::DecreasingStepsize) ) end """ - DecreasingLength(M; kwargs...) DegreasingLength(; kwargs...) + DecreasingLength(M::AbstractManifold; kwargs...) Specify a [`Stepsize`] that is decreasing as ``s_k = $(_tex(:frac, "(l - ak)f^i", "(k+s)^e")) with the following @@ -208,7 +208,7 @@ with the following * `:relative` – scale the gradient tangent vector ``X`` to ``s_k*X`` * `:absolute` – scale the gradient to an absolute step length ``s_k``, that is ``$(_tex(:frac, "s_k", _tex(:norm, "X")))X`` -$(_note(:ManifoldDefaultFactory, "NesterovRule")) +$(_note(:ManifoldDefaultFactory, "DecreasingStepsize")) """ function DecreasingLength(args...; kwargs...) return ManifoldDefaultsFactory(Manopt.DecreasingStepsize, args...; kwargs...) @@ -404,11 +404,11 @@ function set_parameter!(a::ArmijoLinesearchStepsize, ::Val{:IncreaseCondition}, end """ ArmijoLinesearch(; kwargs...) - ArmijoLinesearch(M; kwargs...) + ArmijoLinesearch(M::AbstractManifold; kwargs...) -Specify a step size that performs an Armijo line search. Given a Function `f:$(_math(:M))→ℝ` -and its Riemannian Gradient ``$(_tex(:grad))f:$(_math(:M))→$(_math(:TM))`, -the curent point ``p∈$(_math(:M))`` and a search direction `X∈$(_math(:TpM))``. +Specify a step size that performs an Armijo line search. Given a Function ``f:$(_math(:M))→ℝ`` +and its Riemannian Gradient ``$(_tex(:grad))f: $(_math(:M))→$(_math(:TM))``, +the curent point ``p∈$(_math(:M))`` and a search direction ``X∈$(_math(:TpM))``. Then the step size ``s`` is found by reducing the initial step size ``s`` until @@ -450,6 +450,7 @@ function ArmijoLinesearch(args...; kwargs...) return ManifoldDefaultsFactory(Manopt.ArmijoLinesearchStepsize, args...; kwargs...) end + @doc """ AdaptiveWNGradientStepsize{I<:Integer,R<:Real,F<:Function} <: Stepsize @@ -569,7 +570,7 @@ function show(io::IO, awng::AdaptiveWNGradientStepsize) end """ AdaptiveWNGradient(; kwargs...) - AdaptiveWNGradient(M; kwargs...) + AdaptiveWNGradient(M::AbstractManifold; kwargs...) A stepsize based on the adaptive gradient method introduced by [GrapigliaStella:2023](@cite). @@ -1001,7 +1002,7 @@ get_message(a::NonmonotoneLinesearchStepsize) = a.message @doc """ NonmonotoneLinesearch(; kwargs...) - NonmonotoneLinesearch(M; kwargs...) + NonmonotoneLinesearch(M::AbstractManifold; kwargs...) A functor representing a nonmonotone line search using the Barzilai-Borwein step size [IannazzoPorcelli:2017](@cite). @@ -1021,10 +1022,10 @@ where ``α_{k-1}`` is the step size computed in the last iteration and ``$(_math Then the Barzilai—Borwein step size is ```math -α_k^{$(_tex(:text, "BB"))} = \begin{cases} -$(_tex(:min))(α_{$(_tex(:text, "max"))}, $(_tex(:max))(α_{$(_tex(:text, "min"))}, τ_{k})), & $(_tex(:text, "if")) ⟨s_{k}, y_{k}⟩_{p_k} > 0,\\ -α_{$(_tex(:text, "max"))}, & \text{else,} -\end{cases} +α_k^{$(_tex(:text, "BB"))} = $(_tex(:cases, +"$(_tex(:min))(α_{$(_tex(:text, "max"))}, $(_tex(:max))(α_{$(_tex(:text, "min"))}, τ_{k})), & $(_tex(:text, "if")) ⟨s_{k}, y_{k}⟩_{p_k} > 0,", +"α_{$(_tex(:text, "max"))}, & $(_tex(:text, "else,"))" +)) ``` where @@ -1065,7 +1066,7 @@ $(_var(:Keyword, :p; add="to store an interim result")) * `bb_max_stepsize=1e3`: upper bound for the Barzilai-Borwein step size greater than min_stepsize $(_var(:Keyword, :retraction_method)) * `strategy=direct`: defines if the new step size is computed using the `:direct`, `:indirect` or `:alternating` strategy -* `storage=[`StoreStateAction`](@ref)`(M; store_fields=[:Iterate, :Gradient])``: increase efficiency by using a [`StoreStateAction`](@ref) for `:Iterate` and `:Gradient` +* `storage=`[`StoreStateAction`](@ref)`(M; store_fields=[:Iterate, :Gradient])`: increase efficiency by using a [`StoreStateAction`](@ref) for `:Iterate` and `:Gradient`. * `stepsize_reduction=0.5`: step size reduction factor contained in the interval ``(0,1)`` * `sufficient_decrease=1e-4`: sufficient decrease parameter contained in the interval ``(0,1)`` * `stop_when_stepsize_less=0.0`: smallest stepsize when to stop (the last one before is taken) @@ -1129,7 +1130,7 @@ function show(io::IO, ps::PolyakStepsize) end """ Polyak(; kwargs...) - Polyak(M; kwargs...) + Polyak(M::AbstractManifold; kwargs...) Compute a step size according to a method propsed by Polyak, cf. the Dynamic step size discussed in Section 3.2 of [Bertsekas:2015](@cite). @@ -1326,7 +1327,7 @@ function status_summary(a::WolfePowellLinesearchStepsize) end """ WolfePowellLinesearch(; kwargs...) - WolfePowellLinesearch(M; kwargs...) + WolfePowellLinesearch(M::AbstractManifold; kwargs...) Perform a lineseach to fulfull both the Armijo-Goldstein conditions ```math @@ -1501,7 +1502,7 @@ Then the following Algorithm is performed similar to Algorithm 7 from [Huang:201 """ WolfePowellBinaryLinesearch(; kwargs...) - WolfePowellBinaryLinesearch(M; kwargs...) + WolfePowellBinaryLinesearch(M::AbstractManifold; kwargs...) Perform a lineseach to fulfull both the Armijo-Goldstein conditions for some given sufficient decrease coefficient ``c_1`` and some sufficient curvature condition coefficient``c_2``. diff --git a/src/solvers/DouglasRachford.jl b/src/solvers/DouglasRachford.jl index 9dc4e2ecb4..871c16eed3 100644 --- a/src/solvers/DouglasRachford.jl +++ b/src/solvers/DouglasRachford.jl @@ -21,7 +21,7 @@ $(_var(:Field, :stopping_criterion, "stop")) # Constructor - DouglasRachfordState(M; kwargs...) + DouglasRachfordState(M::AbstractManifold; kwargs...) # Input diff --git a/src/solvers/NelderMead.jl b/src/solvers/NelderMead.jl index 8159b7369a..500fc3c3cb 100644 --- a/src/solvers/NelderMead.jl +++ b/src/solvers/NelderMead.jl @@ -73,7 +73,7 @@ $(_var(:Field, :retraction_method)) # Constructors - NelderMeadState(M; kwargs...) + NelderMeadState(M::AbstractManifold; kwargs...) Construct a Nelder-Mead Option with a default population (if not provided) of set of `dimension(M)+1` random points stored in [`NelderMeadSimplex`](@ref). diff --git a/src/solvers/alternating_gradient_descent.jl b/src/solvers/alternating_gradient_descent.jl index aa471fab8a..f6f7a6a707 100644 --- a/src/solvers/alternating_gradient_descent.jl +++ b/src/solvers/alternating_gradient_descent.jl @@ -20,7 +20,7 @@ $(_var(:Field, :X; add=[:as_Gradient])) # Constructors - AlternatingGradientDescentState(M; kwargs...) + AlternatingGradientDescentState(M::AbstractManifold; kwargs...) # Keyword arguments * `inner_iterations=5` diff --git a/src/solvers/gradient_descent.jl b/src/solvers/gradient_descent.jl index 79f7aa33a4..66f36764fd 100644 --- a/src/solvers/gradient_descent.jl +++ b/src/solvers/gradient_descent.jl @@ -16,7 +16,7 @@ $(_var(:Field, :retraction_method)) # Constructor - GradientDescentState(M; kwargs...) + GradientDescentState(M::AbstractManifold; kwargs...) Initialize the gradient descent solver state, where diff --git a/src/solvers/stochastic_gradient_descent.jl b/src/solvers/stochastic_gradient_descent.jl index 0b0f596d9f..d647f83cde 100644 --- a/src/solvers/stochastic_gradient_descent.jl +++ b/src/solvers/stochastic_gradient_descent.jl @@ -17,7 +17,7 @@ $(_var(:Field, :retraction_method)) # Constructor - StochasticGradientDescentState(M; kwargs...) + StochasticGradientDescentState(M::AbstractManifold; kwargs...) Create a `StochasticGradientDescentState` with start point `p`.