From bfe4d37ced5f0e1c91fd6f7438b3052e63db0149 Mon Sep 17 00:00:00 2001 From: Ronny Bergmann Date: Wed, 21 Aug 2024 20:25:18 +0200 Subject: [PATCH] Simplify first Keyword which is now really much nicer to write. --- docs/src/solvers/conjugate_residual.md | 1 + src/documentation_glossary.jl | 45 +++++++++++----- src/plans/conjugate_gradient_plan.jl | 2 +- src/plans/conjugate_residual_plan.jl | 14 +++-- src/plans/hessian_plan.jl | 27 ++++++---- src/plans/higher_order_primal_dual_plan.jl | 2 +- src/plans/interior_point_Newton_plan.jl | 4 +- src/plans/nonlinear_least_squares_plan.jl | 2 +- src/plans/proximal_plan.jl | 2 +- src/plans/solver_state.jl | 6 +-- src/plans/stepsize.jl | 54 ++++++++++--------- src/solvers/ChambollePock.jl | 2 +- src/solvers/DouglasRachford.jl | 4 +- src/solvers/FrankWolfe.jl | 5 +- src/solvers/Lanczos.jl | 2 +- src/solvers/LevenbergMarquardt.jl | 2 +- src/solvers/NelderMead.jl | 2 +- .../adaptive_regularization_with_cubics.jl | 16 +++--- src/solvers/alternating_gradient_descent.jl | 6 +-- src/solvers/augmented_Lagrangian_method.jl | 5 +- src/solvers/cma_es.jl | 8 +-- src/solvers/conjugate_gradient_descent.jl | 2 +- src/solvers/conjugate_residual.jl | 26 ++++----- src/solvers/convex_bundle_method.jl | 4 +- src/solvers/cyclic_proximal_point.jl | 2 +- .../difference-of-convex-proximal-point.jl | 7 +-- src/solvers/difference_of_convex_algorithm.jl | 4 +- src/solvers/exact_penalty_method.jl | 2 +- src/solvers/gradient_descent.jl | 5 +- src/solvers/interior_point_Newton.jl | 3 +- src/solvers/particle_swarm.jl | 4 +- src/solvers/primal_dual_semismooth_Newton.jl | 2 +- src/solvers/proximal_bundle_method.jl | 4 +- src/solvers/quasi_Newton.jl | 6 +-- src/solvers/stochastic_gradient_descent.jl | 4 +- src/solvers/subgradient.jl | 6 +-- .../truncated_conjugate_gradient_descent.jl | 10 ++-- src/solvers/trust_regions.jl | 4 +- 38 files changed, 167 insertions(+), 139 deletions(-) diff --git a/docs/src/solvers/conjugate_residual.md b/docs/src/solvers/conjugate_residual.md index 0ed7f404b7..7723aeff02 100644 --- a/docs/src/solvers/conjugate_residual.md +++ b/docs/src/solvers/conjugate_residual.md @@ -6,6 +6,7 @@ CurrentModule = Manopt ```@docs conjugate_residual +conjugate_residual! ``` ## State diff --git a/src/documentation_glossary.jl b/src/documentation_glossary.jl index 162d87f013..ccf8d41995 100644 --- a/src/documentation_glossary.jl +++ b/src/documentation_glossary.jl @@ -55,16 +55,19 @@ define!(:LaTeX, :ast, raw"\ast") define!(:LaTeX, :bar, (letter) -> raw"\bar" * "$(letter)") define!(:LaTeX, :bigl, raw"\bigl") define!(:LaTeX, :bigr, raw"\bigr") +define!(:LaTeX, :Bigl, raw"\Bigl") +define!(:LaTeX, :Bigr, raw"\Bigr") define!(:LaTeX, :Cal, (letter) -> raw"\mathcal " * "$letter") define!(:LaTeX, :displaystyle, raw"\displaystyle") define!(:LaTeX, :frac, (a, b) -> raw"\frac" * "{$a}{$b}") define!(:LaTeX, :grad, raw"\operatorname{grad}") +define!(:LaTeX, :hat, (letter) -> raw"\hat{" * "$letter" * "}") define!(:LaTeX, :Hess, raw"\operatorname{Hess}") define!(:LaTeX, :invretr, raw"\operatorname{retr}^{-1}") define!(:LaTeX, :log, raw"\log") define!(:LaTeX, :max, raw"\max") define!(:LaTeX, :min, raw"\min") -define!(:LaTeX, :norm, (v; index = "") -> raw"\lVert" * "$v" * raw"\rVert" * "_{$index}") +define!(:LaTeX, :norm, (v; index = "") -> raw"\lVert " * "$v" * raw" \rVert" * "_{$index}") define!(:LaTeX, :prox, raw"\operatorname{prox}") define!(:LaTeX, :reflect, raw"\operatorname{refl}") define!(:LaTeX, :retr, raw"\operatorname{retr}") @@ -157,8 +160,8 @@ define!( define!( :Variable, :Field, - (s::Symbol, display="$s", t=""; kwargs...) -> - "* `$(display)::$(length(t) > 0 ? t : _var(s, :type))`: $(_var(s, :description; kwargs...))", + (s::Symbol, display="$s", t=""; comment="", kwargs...) -> + "* `$(display)::$(length(t) > 0 ? t : _var(s, :type))`: $(_var(s, :description; kwargs...))$(comment)", ) define!( :Variable, @@ -168,15 +171,39 @@ define!( display="$s", t=""; default="", + comment="", type=false, description::Bool=true, kwargs..., ) -> - "* `$(display)$(type ? "::$(length(t) > 0 ? t : _var(s, :type))" : "")=`$(length(default) > 0 ? default : _var(s, :default; kwargs...))$(description ? ": $(_var(s, :description; kwargs...))" : "")", + "* `$(display)$(type ? "::$(length(t) > 0 ? t : _var(s, :type))" : "")=`$(length(default) > 0 ? default : _var(s, :default; kwargs...))$(description ? ": $(_var(s, :description; kwargs...))" : "")$(comment)", ) # # Actual variables +define!( + :Variable, + :at_iteration, + :description, + "an integer indicating at which the stopping criterion last indicted to stop, which might also be before the solver started (`0`). Any negative value indicates that this was not yet the case;", +) +define!(:Variable, :at_iteration, :type, "Int") + +define!( + :Variable, + :evaluation, + :description, + "specify whether the functions that return an array, for example a point or a tangent vector, work by allocating its result ([`AllocatingEvaluation`](@ref)) or whether they modify their input argument to return the result therein ([`InplaceEvaluation`](@ref)). Since usually the first argument is the manifold, the modified argument is the second.", +) +define!(:Variable, :evaluation, :type, "AbstractEvaluationType") +define!(:Variable, :evaluation, :default, "[`AllocatingEvaluation`](@ref)`()`") +define!( + :Variable, + :evaluation, + :GradientExample, + "For example `grad_f(M,p)` allocates, but `grad_f!(M, X, p)` computes the result in-place of `X`.", +) + define!( :Variable, :f, @@ -287,9 +314,9 @@ define!( :X, :description, (; M="M", p="p", note="") -> - "a tangent bector at the point ``$p`` on the manifold ``$(_tex(:Cal, M))``. $note", + "a tangent vector at the point ``$p`` on the manifold ``$(_tex(:Cal, M))``. $note", ) -define!(:Variable, :X, :type, "X") +define!(:Variable, :X, :type, "T") define!(:Variable, :X, :default, (; M="M", p="p") -> _link(:zero_vector; M=M, p=p)) # @@ -366,8 +393,6 @@ _sc(args...; kwargs...) = glossary(:StoppingCriterion, args...; kwargs...) # Old strings # Fields -_field_at_iteration = "`at_iteration`: an integer indicating at which the stopping criterion last indicted to stop, which might also be before the solver started (`0`). Any negative value indicates that this was not yet the case; " -_field_iterate = "`p`: the current iterate ``p=p^{(k)} ∈ $(_math(:M))``" _field_gradient = "`X`: the current gradient ``$(_tex(:grad))f(p^{(k)}) ∈ T_p$(_math(:M))``" _field_subgradient = "`X` : the current subgradient ``$(_tex(:subgrad))f(p^{(k)}) ∈ T_p$(_tex(:Cal, "M"))``" _field_inv_retr = "`inverse_retraction_method::`[`AbstractInverseRetractionMethod`](@extref `ManifoldsBase.AbstractInverseRetractionMethod`) : an inverse retraction ``$(_tex(:invretr))``" @@ -382,10 +407,6 @@ _field_X = "`X`: a tangent vector" # # # Keywords -_kw_evaluation_default = "`evaluation=`[`AllocatingEvaluation`](@ref)`()`" -_kw_evaluation = "specify whether the functions that return an array, for example a point or a tangent vector, work by allocating its result ([`AllocatingEvaluation`](@ref)) or whether they modify their input argument to return the result therein ([`InplaceEvaluation`](@ref)). Since usually the first argument is the manifold, the modified argument is the second." -_kw_evaluation_example = "For example `grad_f(M,p)` allocates, but `grad_f!(M, X, p)` computes the result in-place of `X`." - _kw_inverse_retraction_method_default = "`inverse_retraction_method=`[`default_inverse_retraction_method`](@extref `ManifoldsBase.default_inverse_retraction_method-Tuple{AbstractManifold}`)`(M, typeof(p))`" _kw_inverse_retraction_method = "an inverse retraction ``$(_tex(:invretr))`` to use, see [the section on retractions and their inverses](@extref ManifoldsBase :doc:`retractions`)." diff --git a/src/plans/conjugate_gradient_plan.jl b/src/plans/conjugate_gradient_plan.jl index bd9a06c961..590404b65c 100644 --- a/src/plans/conjugate_gradient_plan.jl +++ b/src/plans/conjugate_gradient_plan.jl @@ -27,7 +27,7 @@ specify options for a conjugate gradient descent algorithm, that solves a # Fields -$(_var(:Field, :p)) +$(_var(:Field, :p; comment=" storing the current iterate")) $(_var(:Field, :X)) * `δ`: the current descent direction, also a tangent vector * `β`: the current update coefficient rule, see . diff --git a/src/plans/conjugate_residual_plan.jl b/src/plans/conjugate_residual_plan.jl index 5716a6fc7a..b667fb12b1 100644 --- a/src/plans/conjugate_residual_plan.jl +++ b/src/plans/conjugate_residual_plan.jl @@ -189,22 +189,20 @@ A state for the [`conjugate_residual`](@ref) solver. # Constructor - function ConjugateResidualState(TpM::TangentSpace,slso::SymmetricLinearSystemObjective; - kwargs... - ) + ConjugateResidualState(TpM::TangentSpace,slso::SymmetricLinearSystemObjective; kwargs...) Initialise the state with default values. ## Keyword arguments -* `X``$(_link(:zero_vector))` -* `r=-get_gradient(TpM, slso, X)` +* `r=-`[`get_gradient`](@ref)`(TpM, slso, X)` * `d=copy(TpM, r)` -* `Ar=get_hessian(TpM, slso, X, r)` +* `Ar=`[`get_hessian`](@ref)`(TpM, slso, X, r)` * `Ad=copy(TpM, Ar)` * `α::R=0.0` * `β::R=0.0` -* `stopping_criterion=`[`StopAfterIteration`](@ref)`($(_link(:manifold_dimension)))`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-8)` +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(`$(_link(:manifold_dimension))`)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-8)` +$(_var(:Keyword, :X)) # See also @@ -300,7 +298,7 @@ from the [`conjugate_residual`](@ref) # Fields -$(_field_at_iteration) +$(_var(:Field, :at_iteration)) * `c`: the initial norm * `ε`: the threshold * `norm_rk`: the last computed norm of the residual diff --git a/src/plans/hessian_plan.jl b/src/plans/hessian_plan.jl index de9a55275a..c7bead3df2 100644 --- a/src/plans/hessian_plan.jl +++ b/src/plans/hessian_plan.jl @@ -244,7 +244,7 @@ $_doc_ApproxHessian_formula ## Keyword arguments -* `evaluation=`[`AllocatingEvaluation`](@ref)) whether the gradient is given as an allocation function or an in-place ([`InplaceEvaluation`](@ref)). +$(_var(:Keyword, :evaluation)) * `steplength=`2^{-14}``: step length ``c`` to approximate the gradient evaluations * $_kw_retraction_method_default $_kw_retraction_method @@ -311,7 +311,7 @@ function (f::ApproxHessianFiniteDifference{InplaceEvaluation})(M, Y, p, X) return Y end -@doc raw""" +@doc """ ApproxHessianSymmetricRankOne{E, P, G, T, B<:AbstractBasis{ℝ}, VTR, R<:Real} <: AbstractApproxHessian A functor to approximate the Hessian by the symmetric rank one update. @@ -338,8 +338,8 @@ A functor to approximate the Hessian by the symmetric rank one update. * `initial_operator` (`Matrix{Float64}(I, manifold_dimension(M), manifold_dimension(M))`) the matrix representation of the initial approximating operator. * `basis` (`DefaultOrthonormalBasis()`) an orthonormal basis in the tangent space of the initial iterate p. * `nu` (`-1`) -* `evaluation` ([`AllocatingEvaluation`](@ref)) whether the gradient is given as an allocation function or an in-place ([`InplaceEvaluation`](@ref)). -* `vector_transport_method` (`ParallelTransport()`) vector transport ``\mathcal T_{\cdot\gets\cdot}`` to use. +$(_var(:Keyword, :evaluation)) +* `vector_transport_method` (`ParallelTransport()`) vector transport ``$(_math(:vector_transport, :symbol))`` to use. """ mutable struct ApproxHessianSymmetricRankOne{E,P,G,T,B<:AbstractBasis{ℝ},VTR,R<:Real} <: AbstractApproxHessian @@ -458,26 +458,33 @@ function update_hessian_basis!(M, f::ApproxHessianSymmetricRankOne{InplaceEvalua return f.gradient!!(M, f.grad_tmp, f.p_tmp) end -@doc raw""" +@doc """ ApproxHessianBFGS{E, P, G, T, B<:AbstractBasis{ℝ}, VTR, R<:Real} <: AbstractApproxHessian A functor to approximate the Hessian by the BFGS update. + # Fields + * `gradient!!` the gradient function (either allocating or mutating, see `evaluation` parameter). * `scale` * `vector_transport_method` a vector transport to use. + ## Internal temporary fields + * `p_tmp` a temporary storage the current point `p`. * `grad_tmp` a temporary storage for the gradient at the current `p`. * `matrix` a temporary storage for the matrix representation of the approximating operator. * `basis` a temporary storage for an orthonormal basis at the current `p`. + # Constructor ApproxHessianBFGS(M, p, gradF; kwargs...) + ## Keyword arguments + * `initial_operator` (`Matrix{Float64}(I, manifold_dimension(M), manifold_dimension(M))`) the matrix representation of the initial approximating operator. * `basis` (`DefaultOrthonormalBasis()`) an orthonormal basis in the tangent space of the initial iterate p. * `nu` (`-1`) -* `evaluation` ([`AllocatingEvaluation`](@ref)) whether the gradient is given as an allocation function or an in-place ([`InplaceEvaluation`](@ref)). -* `vector_transport_method` (`ParallelTransport()`) vector transport ``\mathcal T_{\cdot\gets\cdot}`` to use. +$(_var(:Keyword, :evaluation)) +$(_var(:Keyword, :vector_transport_method)) """ mutable struct ApproxHessianBFGS{ E,P,G,T,B<:AbstractBasis{ℝ},VTR<:AbstractVectorTransportMethod @@ -500,15 +507,15 @@ function ApproxHessianBFGS( basis::B=DefaultOrthonormalBasis(), scale::Bool=true, evaluation=AllocatingEvaluation(), - vector_transport_method::VTR=ParallelTransport(), -) where {mT<:AbstractManifold,P,G,B<:AbstractBasis{ℝ},VTR<:AbstractVectorTransportMethod} + vector_transport_method::VTM=default_vector_transport_method(M, typeof(p)), +) where {mT<:AbstractManifold,P,G,B<:AbstractBasis{ℝ},VTM<:AbstractVectorTransportMethod} if evaluation == AllocatingEvaluation() grad_tmp = gradient(M, p) elseif evaluation == InplaceEvaluation() grad_tmp = zero_vector(M, p) gradient(M, grad_tmp, p) end - return ApproxHessianBFGS{typeof(evaluation),P,G,typeof(grad_tmp),B,VTR}( + return ApproxHessianBFGS{typeof(evaluation),P,G,typeof(grad_tmp),B,VTM}( p, gradient, grad_tmp, initial_operator, basis, vector_transport_method, scale ) end diff --git a/src/plans/higher_order_primal_dual_plan.jl b/src/plans/higher_order_primal_dual_plan.jl index ce42c612f2..c79879daa0 100644 --- a/src/plans/higher_order_primal_dual_plan.jl +++ b/src/plans/higher_order_primal_dual_plan.jl @@ -70,7 +70,7 @@ end $(_var(:Field, :p, "m")) $(_var(:Field, :p, "n", "Q"; M="N")) -$(_var(:Field, :p)) +$(_var(:Field, :p; comment=" storing the current iterate")) $(_var(:Field, :X)) * `primal_stepsize::Float64`: proximal parameter of the primal prox * `dual_stepsize::Float64`: proximal parameter of the dual prox diff --git a/src/plans/interior_point_Newton_plan.jl b/src/plans/interior_point_Newton_plan.jl index e5b943d6c8..4cc90b91d6 100644 --- a/src/plans/interior_point_Newton_plan.jl +++ b/src/plans/interior_point_Newton_plan.jl @@ -29,13 +29,13 @@ set_iterate!(s::StepsizeState, M, p) = copyto!(M, s.p, p) set_gradient!(s::StepsizeState, M, p, X) = copyto!(M, s.X, p, X) @doc """ - InteriorPointNewtonState <: AbstractHessianSolverState + InteriorPointNewtonState{P,T} <: AbstractHessianSolverState # Fields * `λ`: the Lagrange multiplier with respect to the equality constraints * `μ`: the Lagrange multiplier with respect to the inequality constraints -* `p`: the current iterate +$(_var(:Field, :p; comment=" storing the current iterate")) * `s`: the current slack variable * `sub_problem`: an [`AbstractManoptProblem`](@ref) problem for the subsolver * `sub_state`: an [`AbstractManoptSolverState`](@ref) for the subsolver diff --git a/src/plans/nonlinear_least_squares_plan.jl b/src/plans/nonlinear_least_squares_plan.jl index bd79ccb8a1..dd9b2acac1 100644 --- a/src/plans/nonlinear_least_squares_plan.jl +++ b/src/plans/nonlinear_least_squares_plan.jl @@ -138,7 +138,7 @@ Describes a Gradient based descent algorithm, with A default value is given in brackets if a parameter can be left out in initialization. -* $_field_iterate +$(_var(:Field, :p; comment=" storing the current iterate")) * $_field_stop * $_field_retr * `residual_values`: value of ``F`` calculated in the solver setup or the previous iteration diff --git a/src/plans/proximal_plan.jl b/src/plans/proximal_plan.jl index bf6a8ab2d3..565a231966 100644 --- a/src/plans/proximal_plan.jl +++ b/src/plans/proximal_plan.jl @@ -139,7 +139,7 @@ stores options for the [`cyclic_proximal_point`](@ref) algorithm. These are the # Fields -$(_var(:Field, :p)) +$(_var(:Field, :p; comment=" storing the current iterate")) * $_field_stop * `λ`: a function for the values of ``λ_k`` per iteration(cycle ``ì`` * `oder_type`: whether to use a randomly permuted sequence (`:FixedRandomOrder`), diff --git a/src/plans/solver_state.jl b/src/plans/solver_state.jl index 6b40376759..afcc9fae98 100644 --- a/src/plans/solver_state.jl +++ b/src/plans/solver_state.jl @@ -1,7 +1,7 @@ @inline _extract_val(::Val{T}) where {T} = T -@doc raw""" +@doc """ AbstractManoptSolverState A general super type for all solver states. @@ -9,9 +9,9 @@ A general super type for all solver states. # Fields The following fields are assumed to be default. If you use different ones, -provide the access functions accordingly +adapt the the access functions [`get_iterate`](@ref) and [`get_stopping_criterion`](@ref) accordingly -* `p` a point on a manifold with the current iterate +$(_var(:Field, :p; comment=" storing the current iterate")) * `stop` a [`StoppingCriterion`](@ref). """ abstract type AbstractManoptSolverState end diff --git a/src/plans/stepsize.jl b/src/plans/stepsize.jl index e60ad010f7..b70827eb04 100644 --- a/src/plans/stepsize.jl +++ b/src/plans/stepsize.jl @@ -1183,51 +1183,53 @@ function status_summary(a::WolfePowellBinaryLinesearch) return "$a$s" end -@doc raw""" +_awng_cases = raw""" +```math +(b_k, ω_k, c_k) = \begin{cases} +\bigl(\hat b_{k-1}, \lVert X_k\rVert_{p_k}, 0 \bigr) & \text{ if } c_{k-1}+1 = \hat c\\ +\Bigl(b_{k-1} + \frac{\lVert X_k\rVert_{p_k}^2}{b_{k-1}}, \omega_{k-1}, c_{k-1}+1 \Bigr) & \text{ if } c_{k-1}+1<\hat c +\end{cases} +``` +""" +@doc """ AdaptiveWNGradient <: DirectionUpdateRule Represent an adaptive gradient method introduced by [GrapigliaStella:2023](@cite). -Given a positive threshold ``\hat c \mathbb N``, -an minimal bound ``b_{\mathrm{min}} > 0``, -an initial ``b_0 ≥ b_{\mathrm{min}}``, and a -gradient reduction factor threshold ``\alpha ∈ [0,1)``. +Given a positive threshold ``$(_tex(:hat, "c")) ∈ ℕ``, +an minimal bound ``b_{$(_tex(:text, "min"))} > 0``, +an initial ``b_0 ≥ b_{$(_tex(:text, "min"))}``, and a +gradient reduction factor threshold ``α ∈ [0,1)``. -Set ``c_0=0`` and use ``\omega_0 = \lVert \operatorname{grad} f(p_0) \rvert_{p_0}``. +Set ``c_0=0`` and use ``ω_0 = $(_tex(:norm, "$(_tex(:grad)) f(p_0)"; index="p_0"))``. -For the first iterate use the initial step size ``s_0 = \frac{1}{b_0}``. +For the first iterate use the initial step size ``s_0 = $(_tex(:frac, "1", "b_0"))``. -Then, given the last gradient ``X_{k-1} = \operatorname{grad} f(x_{k-1})``, -and a previous ``\omega_{k-1}``, the values ``(b_k, \omega_k, c_k)`` are computed -using ``X_k = \operatorname{grad} f(p_k)`` and the following cases +Then, given the last gradient ``X_{k-1} = $(_tex(:grad)) f(x_{k-1})``, +and a previous ``ω_{k-1}``, the values ``(b_k, ω_k, c_k)`` are computed +using ``X_k = $(_tex(:grad)) f(p_k)`` and the following cases -If ``\lVert X_k \rVert_{p_k} \leq \alpha\omega_{k-1}``, then let -``\hat b_{k-1} ∈ [b_\mathrm{min},b_{k-1}]`` and set +If ``$(_tex(:norm, "X_k"; index="p_k")) ≤ αω_{k-1}``, then let +``$(_tex(:hat, "b"))_{k-1} ∈ [b_{$(_tex(:text, "min"))},b_{k-1}]`` and set -```math -(b_k, \omega_k, c_k) = \begin{cases} -\bigl(\hat b_{k-1}, \lVert X_k\rVert_{p_k}, 0 \bigr) & \text{ if } c_{k-1}+1 = \hat c\\ -\Bigl(b_{k-1} + \frac{\lVert X_k\rVert_{p_k}^2}{b_{k-1}}, \omega_{k-1}, c_{k-1}+1 \Bigr) & \text{ if } c_{k-1}+1<\hat c -\end{cases} -``` +$(_awng_cases) -If ``\lVert X_k \rVert_{p_k} > \alpha\omega_{k-1}``, the set +If ``$(_tex(:norm, "X_k"; index="p_k")) > αω_{k-1}``, the set ```math -(b_k, \omega_k, c_k) = -\Bigl( b_{k-1} + \frac{\lVert X_k\rVert_{p_k}^2}{b_{k-1}}, \omega_{k-1}, 0) +(b_k, ω_k, c_k) = $(_tex(:Bigl))( b_{k-1} + $(_tex(:frac, _tex(:norm, "X_k"; index="p_k")*"^2", "b_{k-1}")), ω_{k-1}, 0 $(_tex(:Bigr))) ``` -and return the step size ``s_k = \frac{1}{b_k}``. +and return the step size ``s_k = $(_tex(:frac, "1", "b_k"))``. Note that for ``α=0`` this is the Riemannian variant of `WNGRad`. # Fields -* `count_threshold::Int=4`: an `Integer` for ``\hat c`` -* `minimal_bound::Float64=1e-4`: for ``b_{\mathrm{min}}`` +* `count_threshold::Int=4`: an `Integer` for ``$(_tex(:hat, "c"))`` +* `minimal_bound::Float64=1e-4`: for ``b_{$(_tex(:text, "min"))}`` * `alternate_bound::Function=(bk, hat_c) -> min(gradient_bound, max(gradient_bound, bk/(3*hat_c)`: - how to determine ``\hat b_k`` as a function of `(bmin, bk, hat_c) -> hat_bk` + how to determine ``$(_tex(:hat, "k"))_k`` as a function of `(bmin, bk, hat_c) -> hat_bk` * `gradient_reduction::Float64=0.9`: * `gradient_bound` `norm(M, p0, grad_f(M,p0))` the bound ``b_k``. @@ -1243,7 +1245,7 @@ as well as the internal fields Where all fields with defaults are keyword arguments and additional keyword arguments are * `adaptive=true`: switches the `gradient_reduction ``α`` to `0`. -* `evaluation=AllocatingEvaluation()`: specifies whether the gradient (that is used for initialisation only) is mutating or allocating +$(_var(:Keyword, :evaluation)) """ mutable struct AdaptiveWNGradient{I<:Integer,R<:Real,F<:Function} <: Stepsize count_threshold::I diff --git a/src/solvers/ChambollePock.jl b/src/solvers/ChambollePock.jl index be168807f6..f91f841b17 100644 --- a/src/solvers/ChambollePock.jl +++ b/src/solvers/ChambollePock.jl @@ -238,7 +238,7 @@ For more details on the algorithm, see [BergmannHerzogSilvaLouzeiroTenbrinckVida * `acceleration=0.05`: acceleration parameter * `dual_stepsize=1/sqrt(8)`: proximal parameter of the primal prox -* $_kw_evaluation_default: $_kw_evaluation +$(_var(:Keyword, :evaluation)) * $_kw_inverse_retraction_method_default: $_kw_inverse_retraction_method * `inverse_retraction_method_dual=`[`default_inverse_retraction_method`](@extref `ManifoldsBase.default_inverse_retraction_method-Tuple{AbstractManifold}`)`(N, typeof(n))` an inverse retraction ``$(_tex(:invretr))`` to use on $(_tex(:Cal, "N")), see [the section on retractions and their inverses](@extref ManifoldsBase :doc:`retractions`). diff --git a/src/solvers/DouglasRachford.jl b/src/solvers/DouglasRachford.jl index a6a883ba29..50b20167f7 100644 --- a/src/solvers/DouglasRachford.jl +++ b/src/solvers/DouglasRachford.jl @@ -12,7 +12,7 @@ Store all options required for the DouglasRachford algorithm, * `λ`: function to provide the value for the proximal parameter during the calls * `parallel`: indicate whether to use a parallel Douglas-Rachford or not. * `R`: method employed in the iteration to perform the reflection of `x` at the prox `p`. -* $(_field_iterate) +$(_var(:Field, :p; comment=" storing the current iterate")) For the parallel Douglas-Rachford, this is not a value from the `PowerManifold` manifold but the mean. * `reflection_evaluation`: whether `R` works in-place or allocating * $(_field_retr) @@ -179,7 +179,7 @@ $(_var(:Argument, :p)) * `α= k -> 0.9`: relaxation of the step from old to new iterate, to be precise ``p^{(k+1)} = g(α_k; p^{(k)}, q^{(k)})``, where ``q^{(k)}`` is the result of the double reflection involved in the DR algorithm and ``g`` is a curve induced by the retraction and its inverse. -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * $(_kw_inverse_retraction_method_default): $(_kw_inverse_retraction_method) This is used both in the relaxation step as well as in the reflection, unless you set `R` yourself. * `λ= k -> 1.0`: function to provide the value for the proximal parameter ``λ_k`` diff --git a/src/solvers/FrankWolfe.jl b/src/solvers/FrankWolfe.jl index b94105243f..cd937beca3 100644 --- a/src/solvers/FrankWolfe.jl +++ b/src/solvers/FrankWolfe.jl @@ -14,7 +14,7 @@ It comes in two forms, depending on the realisation of the `subproblem`. # Fields -* $_field_iterate +$(_var(:Field, :p; comment=" storing the current iterate")) * $_field_gradient * $_field_inv_retr * $_field_sub_problem @@ -192,8 +192,7 @@ $(_note(:GradientObjective)) # Keyword arguments -* $_kw_evaluation_default: - $_kw_evaluation $_kw_evaluation_example +$(_var(:Keyword, :evaluation)) * $_kw_retraction_method_default: $_kw_retraction_method diff --git a/src/solvers/Lanczos.jl b/src/solvers/Lanczos.jl index 500119a2b3..f3099a3279 100644 --- a/src/solvers/Lanczos.jl +++ b/src/solvers/Lanczos.jl @@ -260,7 +260,7 @@ $_math_sc_firstorder # Fields * `θ`: the factor ``θ`` in the second condition -* $_field_at_iteration +$(_var(:Field, :at_iteration)) # Constructor diff --git a/src/solvers/LevenbergMarquardt.jl b/src/solvers/LevenbergMarquardt.jl index 48c468d3f0..9d8ed9cd8f 100644 --- a/src/solvers/LevenbergMarquardt.jl +++ b/src/solvers/LevenbergMarquardt.jl @@ -34,7 +34,7 @@ then the keyword `jacobian_tangent_basis` below is ignored # Keyword arguments -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * `η=0.2`: scaling factor for the sufficient cost decrease threshold required to accept new proposal points. Allowed range: `0 < η < 1`. * `expect_zero_residual=false`: whether or not the algorithm might expect that the value of residual (objective) at minimum is equal to 0. diff --git a/src/solvers/NelderMead.jl b/src/solvers/NelderMead.jl index 1508294481..80856694ee 100644 --- a/src/solvers/NelderMead.jl +++ b/src/solvers/NelderMead.jl @@ -67,7 +67,7 @@ after the description * `γ` the expansion parameter ``γ > 0``: * `ρ`: the contraction parameter, ``0 < ρ ≤ \\frac{1}{2}``, * `σ`: the shrinkage coefficient, ``0 < σ ≤ 1`` -* `p`: a field to store the current best value (initialized to _some_ point here) +$(_var(:Field, :p; comment=" storing the current best point")) * $_field_retr * $_field_inv_retr diff --git a/src/solvers/adaptive_regularization_with_cubics.jl b/src/solvers/adaptive_regularization_with_cubics.jl index fa72482281..c68877c846 100644 --- a/src/solvers/adaptive_regularization_with_cubics.jl +++ b/src/solvers/adaptive_regularization_with_cubics.jl @@ -9,7 +9,7 @@ A state for the [`adaptive_regularization_with_cubics`](@ref) solver. * `γ1`, `γ2`: shrinking and expansion factors for regularization parameter `σ` * `H`: the current Hessian evaluation * `s`: the current solution from the subsolver -* $_field_iterate +$(_var(:Field, :p; comment=" storing the current iterate")) * `q`: a point for the candidates to evaluate model and ρ * $_field_gradient * `s`: the tangent vector step resulting from minimizing the model @@ -35,6 +35,8 @@ Furthermore the following integral fields are defined Construct the solver state with all fields stated as keyword arguments and the following defaults +## Keyword arguments + * `η1=0.1` * `η2=0.9` * `γ1=0.1` @@ -42,14 +44,14 @@ Construct the solver state with all fields stated as keyword arguments and the f * `σ=100/manifold_dimension(M)` * `σmin=1e-7 * `ρ_regularization=1e3` -* $_kw_evaluation_default -* $(_kw_p_default) +$(_var(:Keyword, :evaluation)) +$(_var(:Keyword, :p)) * $_kw_retraction_method_default * `stopping_criterion=`[`StopAfterIteration`](@ref)`(100)` * `sub_objective=nothing` a shortcut to provide a subobjective. * `sub_problem=nothing` is set to [`DefaultManoptProblem`](@ref) on the [`TangentSpace`](@extref ManifoldsBase `ManifoldsBase.TangentSpace`) of `p` if an `sub_objecive` is provided * `sub_state` is set to [`AllocatingEvaluation`](@ref) if `sub_problem` is a function and to a [`LanczosState`](@ref) on the tangent space otherwise -* $(_kw_X_default) +$(_var(:Keyword, :X)) """ mutable struct AdaptiveRegularizationState{ P, @@ -236,14 +238,14 @@ the cost `f` and its gradient and Hessian might also be provided as a [`Manifold * `η2=0.9`: upper model success threshold * `γ1=0.1`: regularization reduction factor (for the success case) * `γ2=2.0`: regularization increment factor (for the non-success case) -* $_kw_evaluation_default: - $_kw_evaluation +$(_var(:Keyword, :evaluation)) * `initial_tangent_vector=zero_vector(M, p)`: initialize any tangent vector data, * `maxIterLanczos=200`: a shortcut to set the stopping criterion in the sub solver, * `ρ_regularization=1e3`: a regularization to avoid dividing by zero for small values of cost and model * $_kw_retraction_method_default: $_kw_retraction_method -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(40)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-9)`$(_sc(:Any))[`StopWhenAllLanczosVectorsUsed`](@ref)`(maxIterLanczos)`: + + * `stopping_criterion=`[`StopAfterIteration`](@ref)`(40)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-9)`$(_sc(:Any))[`StopWhenAllLanczosVectorsUsed`](@ref)`(maxIterLanczos)`: $_kw_stopping_criterion * $_kw_sub_kwargs_default: $_kw_sub_kwargs diff --git a/src/solvers/alternating_gradient_descent.jl b/src/solvers/alternating_gradient_descent.jl index 484dbc17a6..d0d205f22b 100644 --- a/src/solvers/alternating_gradient_descent.jl +++ b/src/solvers/alternating_gradient_descent.jl @@ -5,6 +5,7 @@ Store the fields for an alternating gradient descent algorithm, see also [`alternating_gradient_descent`](@ref). # Fields + * `direction`: (`AlternatingGradient(zero_vector(M, x))` a [`DirectionUpdateRule`](@ref) * `evaluation_order`: (`:Linear`) whether to use a randomly permuted sequence (`:FixedRandom`), a per cycle newly permuted sequence (`:Random`) or the default `:Linear` evaluation order. @@ -13,7 +14,7 @@ see also [`alternating_gradient_descent`](@ref). * `retraction_method`: (`default_retraction_method(M, typeof(p))`) a `retraction(M,x,ξ)` to use. * `stepsize`: ([`ConstantStepsize`](@ref)`(M)`) a [`Stepsize`](@ref) * `stopping_criterion`: ([`StopAfterIteration`](@ref)`(1000)`) a [`StoppingCriterion`](@ref) -* `p`: the current iterate +$(_var(:Field, :p; comment=" storing the current iterate")) * `X`: (`zero_vector(M,p)`) the current gradient tangent vector * `k`, ì`: internal counters for the outer and inner iterations, respectively. @@ -169,8 +170,7 @@ $(_var(:Argument, :p)) # Keyword arguments -* $_kw_evaluation_default: - $_kw_evaluation +$(_var(:Keyword, :evaluation)) * `evaluation_order=:Linear`: whether to use a randomly permuted sequence (`:FixedRandom`), a per cycle permuted sequence (`:Random`) or the default `:Linear` one. * `inner_iterations=5`: how many gradient steps to take in a component before alternating to the next diff --git a/src/solvers/augmented_Lagrangian_method.jl b/src/solvers/augmented_Lagrangian_method.jl index 518f4afc3e..7c5e37dc44 100644 --- a/src/solvers/augmented_Lagrangian_method.jl +++ b/src/solvers/augmented_Lagrangian_method.jl @@ -17,7 +17,7 @@ a default value is given in brackets if a parameter can be left out in initializ * `λ`: the Lagrange multiplier with respect to the equality constraints * `λ_max`: an upper bound for the Lagrange multiplier belonging to the equality constraints * `λ_min`: a lower bound for the Lagrange multiplier belonging to the equality constraints -$(_var(:Field, :p)) +$(_var(:Field, :p; comment=" storing the current iterate")) * `penalty`: evaluation of the current penalty term, initialized to `Inf`. * `μ`: the Lagrange multiplier with respect to the inequality constraints * `μ_max`: an upper bound for the Lagrange multiplier belonging to the inequality constraints @@ -283,8 +283,7 @@ Otherwise the problem is not constrained and a better solver would be for exampl # Keyword Arguments -* $_kw_evaluation_default: $_kw_evaluation - +$(_var(:Keyword, :evaluation)) * `ϵ=1e-3`: the accuracy tolerance * `ϵ_min=1e-6`: the lower bound for the accuracy tolerance * `ϵ_exponent=1/100`: exponent of the ϵ update factor; diff --git a/src/solvers/cma_es.jl b/src/solvers/cma_es.jl index 2871b76ed7..b849e903e1 100644 --- a/src/solvers/cma_es.jl +++ b/src/solvers/cma_es.jl @@ -1,14 +1,14 @@ # # State # -@doc raw""" +@doc """ CMAESState{P,T} <: AbstractManoptSolverState State of covariance matrix adaptation evolution strategy. # Fields -* `p` the best point found so far +$(_var(:Field, :p; comment=" storing the best point found so far")) * `p_obj` objective value at `p` * `μ` parent number * `λ` population size @@ -30,8 +30,8 @@ State of covariance matrix adaptation evolution strategy. * `worst_fitness_current_gen` worst fitness value of individuals in the current generation * `p_m` point around which the search for new candidates is done * `σ` step size -* `p_σ` coordinates of a vector in ``T_{p_m} \mathcal M`` -* `p_c` coordinates of a vector in ``T_{p_m} \mathcal M`` +* `p_σ` coordinates of a vector in ``$(_math(:TpM; p="p_m"))`` +* `p_c` coordinates of a vector in ``$(_math(:TpM; p="p_m"))`` * `deviations` standard deviations of coordinate RNG * `buffer` buffer for random number generation and `wmean_y_c` of length `n_coords` * `e_mv_norm` expected value of norm of the `n_coords`-variable standard normal distribution diff --git a/src/solvers/conjugate_gradient_descent.jl b/src/solvers/conjugate_gradient_descent.jl index fbb4df500d..5070f3b839 100644 --- a/src/solvers/conjugate_gradient_descent.jl +++ b/src/solvers/conjugate_gradient_descent.jl @@ -80,7 +80,7 @@ $(_var(:Argument, :p)) rule to compute the descent direction update coefficient ``β_k``, as a functor, where the resulting function maps are `(amp, cgs, k) -> β` with `amp` an [`AbstractManoptProblem`](@ref), `cgs` is the [`ConjugateGradientDescentState`](@ref), and `i` is the current iterate. -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * $(_kw_retraction_method_default): $(_kw_retraction_method) * `stepsize=[`ArmijoLinesearch`](@ref)`(M)`: $_kw_stepsize via [`default_stepsize`](@ref)) passing on the `default_retraction_method` diff --git a/src/solvers/conjugate_residual.jl b/src/solvers/conjugate_residual.jl index 02214bac20..4efad83def 100644 --- a/src/solvers/conjugate_residual.jl +++ b/src/solvers/conjugate_residual.jl @@ -1,8 +1,8 @@ -@doc """ - conjugate_residual(TpM::TangentSpace, A, b, p=rand(TpM)) - conjugate_residual(TpM::TangentSpace, slso::SymmetricLinearSystemObjective, p=rand(TpM)) - conjugate_residual!(TpM::TangentSpace, A, b, p) - conjugate_residual!(TpM::TangentSpace, slso::SymmetricLinearSystemObjective, p) +_doc_conjugate_residual = """ + conjugate_residual(TpM::TangentSpace, A, b, X=zero_vector(TpM)) + conjugate_residual(TpM::TangentSpace, slso::SymmetricLinearSystemObjective, X=zero_vector(TpM)) + conjugate_residual!(TpM::TangentSpace, A, b, X) + conjugate_residual!(TpM::TangentSpace, slso::SymmetricLinearSystemObjective, X) Compute the solution of ``$(_tex(:Cal, "A"))(p)[X] + b(p) = 0_p ``, where @@ -35,19 +35,18 @@ Note that the right hand side of Step 7 is the same as evaluating ``$(_tex(:Cal, * `TpM` the [`TangentSpace`](@extref `ManifoldsBase.TangentSpace`) as the domain * `A` a symmetric linear operator on the tangent space `(M, p, X) -> Y` * `b` a vector field on the tangent space `(M, p) -> X` - +* `X` the initial tangent vector # Keyword arguments -* `evaluation=`[`AllocatingEvaluation`](@ref) specify whether `A` and `b` are implemented allocating or in-place +$(_var(:Keyword, :evaluation)) * `stopping_criterion::`[`StoppingCriterion`](@ref)`=`[`StopAfterIteration`](@ref)`(`$(_link(:manifold_dimension))$(_sc(:Any))[`StopWhenRelativeResidualLess`](@ref)`(c,1e-8)`, - where `c` is the norm of ``$(_tex(:norm,"b"))``. - -# Output + where `c` is ``$(_tex(:norm,"b"))``. -the obtained (approximate) minimizer ``X^*``. -To obtain the whole final state of the solver, see [`get_solver_return`](@ref) for details. +$(_note(:OutputSection)) """ + +@doc "$_doc_conjugate_residual" conjugate_residual(TpM::TangentSpace, args...; kwargs...) function conjugate_residual( @@ -68,6 +67,9 @@ function conjugate_residual( return conjugate_residual!(TpM, slso, Y; kwargs...) end +@doc "$_doc_conjugate_residual" +conjugate_residual!(TpM::TangentSpace, args...; kwargs...) + function conjugate_residual!( TpM::TangentSpace, slso::SymmetricLinearSystemObjective, diff --git a/src/solvers/convex_bundle_method.jl b/src/solvers/convex_bundle_method.jl index e1ff721579..88da719855 100644 --- a/src/solvers/convex_bundle_method.jl +++ b/src/solvers/convex_bundle_method.jl @@ -19,7 +19,7 @@ point type `P` and a tangent vector type `T`` * `k_max::R`: upper bound on the sectional curvature of the manifold * `linearization_errors<:AbstractVector{<:R}`: linearization errors at the last serious step * `m::R`: the parameter to test the decrease of the cost: ``f(q_{k+1}) ≤ f(p_k) + m ξ``. -* $(_field_iterate) +$(_var(:Field, :p; comment=" storing the current iterate")) * `p_last_serious::P`: last serious iterate * $(_field_retr) * $(_field_stop) @@ -310,7 +310,7 @@ $(_var(:Argument, :p)) * `m=1e-3`: : the parameter to test the decrease of the cost: ``f(q_{k+1}) ≤ f(p_k) + m ξ``. * `diameter=50.0`: estimate for the diameter of the level set of the objective function at the starting point. * `domain=(M, p) -> isfinite(f(M, p))`: a function to that evaluates to true when the current candidate is in the domain of the objective `f`, and false otherwise. -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * `k_max=0`: upper bound on the sectional curvature of the manifold. * `stepsize=default_stepsize(M, ConvexBundleMethodState)`, which defaults to [`ConstantStepsize`](@ref)`(M)`. * $(_kw_inverse_retraction_method_default): $(_kw_inverse_retraction_method) diff --git a/src/solvers/cyclic_proximal_point.jl b/src/solvers/cyclic_proximal_point.jl index 1999c456a2..20f0e35762 100644 --- a/src/solvers/cyclic_proximal_point.jl +++ b/src/solvers/cyclic_proximal_point.jl @@ -33,7 +33,7 @@ where `f` and the proximal maps `proxes_f` can also be given directly as a [`Man # Keyword arguments -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * `evaluation_order=:Linear`: whether to use a randomly permuted sequence (`:FixedRandom`:, a per cycle permuted sequence (`:Random`) or the default linear one. * `λ=iter -> 1/iter`: a function returning the (square summable but not summable) sequence of ``λ_i`` diff --git a/src/solvers/difference-of-convex-proximal-point.jl b/src/solvers/difference-of-convex-proximal-point.jl index 96b434c2fc..085beb8e4b 100644 --- a/src/solvers/difference-of-convex-proximal-point.jl +++ b/src/solvers/difference-of-convex-proximal-point.jl @@ -10,8 +10,9 @@ It comes in two forms, depending on the realisation of the `subproblem`. * $(_field_inv_retr) * $(_field_retr) -* `p`, `q`, `r`: the current iterate, the gradient step and the prox, respectively - their type is set by initializing `p` +$(_var(:Field, :p; comment=" storing the current iterate")) +$(_var(:Field, :p, "q"; comment=" storing the gradient step")) +$(_var(:Field, :p, "r"; comment=" storing the result of the proximal map")) * $(_field_step) * $(_field_stop) * `X`, `Y`: the current gradient and descent direction, respectively @@ -190,7 +191,7 @@ DC functions is obtained for ``s_k = 1`` and one can hence employ usual line sea * `λ`: ( `k -> 1/2` ) a function returning the sequence of prox parameters ``λ_k`` * `cost=nothing`: provide the cost `f`, for debug reasons / analysis -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * `gradient=nothing`: specify ``$(_tex(:grad)) f``, for debug / analysis or enhancing the `stopping_criterion` * `prox_g=nothing`: specify a proximal map for the sub problem _or_ both of the following diff --git a/src/solvers/difference_of_convex_algorithm.jl b/src/solvers/difference_of_convex_algorithm.jl index af8e101d22..b8c4143c5b 100644 --- a/src/solvers/difference_of_convex_algorithm.jl +++ b/src/solvers/difference_of_convex_algorithm.jl @@ -8,7 +8,7 @@ It comes in two forms, depending on the realisation of the `subproblem`. # Fields -* $(_field_iterate) +$(_var(:Field, :p; comment=" storing the current iterate")) * $(_field_subgradient) * $(_field_sub_problem) * $(_field_sub_state) @@ -134,7 +134,7 @@ until the stopping criterion (see the `stopping_criterion` keyword is fulfilled. # Keyword arguments -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * `gradient=nothing`: specify ``$(_tex(:grad)) f``, for debug / analysis or enhancing the `stopping_criterion=` * `grad_g=nothing`: specify the gradient of `g`. If specified, a subsolver is automatically set up. * `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-8)`: diff --git a/src/solvers/exact_penalty_method.jl b/src/solvers/exact_penalty_method.jl index 5cb160131b..d21618f0e7 100644 --- a/src/solvers/exact_penalty_method.jl +++ b/src/solvers/exact_penalty_method.jl @@ -7,7 +7,7 @@ Describes the exact penalty method, with * `ϵ`: the accuracy tolerance * `ϵ_min`: the lower bound for the accuracy tolerance -$(_var(:Field, :p)) +$(_var(:Field, :p; comment=" storing the current iterate")) * `ρ`: the penalty parameter * $(_field_sub_problem) * $(_field_sub_state) diff --git a/src/solvers/gradient_descent.jl b/src/solvers/gradient_descent.jl index 2d240740c8..8ee344f102 100644 --- a/src/solvers/gradient_descent.jl +++ b/src/solvers/gradient_descent.jl @@ -6,7 +6,7 @@ Describes the state of a gradient based descent algorithm. # Fields -* $_field_iterate +$(_var(:Field, :p; comment=" storing the current iterate")) * $_field_gradient * $_field_stop * $_field_step @@ -142,8 +142,7 @@ $(_note(:GradientObjective)) specify to perform a certain processing of the direction, for example [`Nesterov`](@ref), [`MomentumGradient`](@ref) or [`AverageGradient`](@ref). -* $_kw_evaluation_default: - $_kw_evaluation $_kw_evaluation_example +$(_var(:Keyword, :evaluation; comment=_var(:evaluation, :GradientExample))) * $_kw_retraction_method_default: $_kw_retraction_method diff --git a/src/solvers/interior_point_Newton.jl b/src/solvers/interior_point_Newton.jl index c1d947a587..ed8765ff5f 100644 --- a/src/solvers/interior_point_Newton.jl +++ b/src/solvers/interior_point_Newton.jl @@ -54,8 +54,7 @@ pass a [`ConstrainedManifoldObjective`](@ref) `cmo` This can be used to ensure that the resulting iterate is still an interior point if you provide a check `(N,q) -> true/false`, where `N` is the manifold of the `step_problem`. * `equality_constraints=nothing`: the number ``n`` of equality constraints. -* `evaluation=`[`AllocatingEvaluation`](@ref)`()`: - specify whether the functions that return an array, for example a point or a tangent vector, work by allocating its result ([`AllocatingEvaluation`](@ref)) or whether they modify their input argument to return the result therein ([`InplaceEvaluation`](@ref)). Since usually the first argument is the manifold, the modified argument is the second. +$(_var(:Keyword, :evaluation)) * `g=nothing`: the inequality constraints * `grad_g=nothing`: the gradient of the inequality constraints * `grad_h=nothing`: the gradient of the equality constraints diff --git a/src/solvers/particle_swarm.jl b/src/solvers/particle_swarm.jl index 2b01a109e6..203ad4d597 100644 --- a/src/solvers/particle_swarm.jl +++ b/src/solvers/particle_swarm.jl @@ -20,9 +20,9 @@ Describes a particle swarm optimizing algorithm, with # Internal and temporary fields * `cognitive_vector`: temporary storage for a tangent vector related to `cognitive_weight` -* `p`: storage for the best point ``p`` visited by all particles. +$(_var(:Field, :p; comment=" storing the best point visited by all particles")) * `positional_best`: storing the best position ``p_i`` every single swarm participant visited -* `q`: temporary storage for a point to avoid allocations during a step of the algorithm +$(_var(:Field, :p, "q"; comment=" serving as temporary storage for interims results; avoids allocations")) * `social_vec`: temporary storage for a tangent vector related to `social_weight` * `swarm`: a set of points (of type `AbstractVector{P}`) on a manifold ``$(_math(:Sequence, "a","i","1","N"))`` diff --git a/src/solvers/primal_dual_semismooth_Newton.jl b/src/solvers/primal_dual_semismooth_Newton.jl index d31be578e9..aced36ae32 100644 --- a/src/solvers/primal_dual_semismooth_Newton.jl +++ b/src/solvers/primal_dual_semismooth_Newton.jl @@ -26,7 +26,7 @@ For more details on the algorithm, see [DiepeveenLellmann:2021](@cite). # Keyword arguments * `dual_stepsize=1/sqrt(8)`: proximal parameter of the dual prox -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * $(_kw_inverse_retraction_method_default): $(_kw_inverse_retraction_method) * `Λ=missing`: the exact operator, that is required if `Λ(m)=n` does not hold; `missing` indicates, that the forward operator is exact. diff --git a/src/solvers/proximal_bundle_method.jl b/src/solvers/proximal_bundle_method.jl index fe2e691856..526d9660ea 100644 --- a/src/solvers/proximal_bundle_method.jl +++ b/src/solvers/proximal_bundle_method.jl @@ -20,7 +20,7 @@ stores option values for a [`proximal_bundle_method`](@ref) solver. * `m`: the parameter to test the decrease of the cost * `μ`: (initial) proximal parameter for the subproblem * `ν`: the stopping parameter given by ``ν = - μ |d|^2 - c`` -* `p`: current candidate point +$(_var(:Field, :p; comment=" storing the current iterate")) * `p_last_serious`: last serious iterate * $(_field_retr) * $(_field_stop) @@ -242,7 +242,7 @@ $(_var(:Argument, :p)) * `bundle_size=50`: the maximal size of the bundle * `δ=1.0`: parameter for updating `μ`: if ``δ < 0`` then ``μ = \\log(i + 1)``, else ``μ += δ μ`` * `ε=1e-2`: stepsize-like parameter related to the injectivity radius of the manifold -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * $(_kw_inverse_retraction_method_default): $(_kw_inverse_retraction_method) * `m=0.0125`: a real number that controls the decrease of the cost function * `μ=0.5`: initial proximal parameter for the subproblem diff --git a/src/solvers/quasi_Newton.jl b/src/solvers/quasi_Newton.jl index 05714b18a6..128b0e8ba9 100644 --- a/src/solvers/quasi_Newton.jl +++ b/src/solvers/quasi_Newton.jl @@ -10,7 +10,7 @@ all necessary fields. * `η`: the current update direction * `nondescent_direction_behavior`: a `Symbol` to specify how to handle direction that are not descent ones. * `nondescent_direction_value`: the value from the last inner product from checking for descent directions -$(_var(:Field, :p)) +$(_var(:Field, :p; comment=" storing the current iterate")) * `p_old`: the last iterate * `sk`: the current step * `yk`: the current gradient difference @@ -212,9 +212,7 @@ $(_var(:Argument, :p)) and strictly increasing at ``0`` * `direction_update=`[`InverseBFGS`](@ref)`()`: the [`AbstractQuasiNewtonUpdateRule`](@ref) to use. -* $(_kw_evaluation_default): - $(_kw_evaluation) - $(_kw_evaluation_example) +$(_var(:Keyword, :evaluation; comment=_var(:evaluation, :GradientExample))) * `initial_operator= initial_scale*Matrix{Float64}(I, n, n)`: initial matrix to use in case the Hessian (inverse) approximation is stored as a full matrix, that is `n=manifold_dimension(M)`. This matrix is only allocated for the full matrix case. diff --git a/src/solvers/stochastic_gradient_descent.jl b/src/solvers/stochastic_gradient_descent.jl index 782f497bca..20e4068f76 100644 --- a/src/solvers/stochastic_gradient_descent.jl +++ b/src/solvers/stochastic_gradient_descent.jl @@ -6,7 +6,7 @@ see also [`ManifoldStochasticGradientObjective`](@ref) and [`stochastic_gradient # Fields -* $(_field_iterate) +$(_var(:Field, :p; comment=" storing the current iterate")) * `direction`: a direction update to use * $(_field_stop) * $(_field_step) @@ -162,7 +162,7 @@ then using the `cost=` keyword does not have any effect since if so, the cost is * `cost=missing`: you can provide a cost function for example to track the function value * `direction=`[`StochasticGradient`](@ref)`($(_link(:zero_vector))) -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * `evaluation_order=:Random`: specify whether to use a randomly permuted sequence (`:FixedRandom`:, a per cycle permuted sequence (`:Linear`) or the default `:Random` one. * `order_type=:RandomOder`: a type of ordering of gradient evaluations. diff --git a/src/solvers/subgradient.jl b/src/solvers/subgradient.jl index c1206e4acf..b245b386a1 100644 --- a/src/solvers/subgradient.jl +++ b/src/solvers/subgradient.jl @@ -5,7 +5,7 @@ stores option values for a [`subgradient_method`](@ref) solver # Fields -$(_var(:Field, :p)) +$(_var(:Field, :p; comment=" storing the current iterate")) * `p_star`: optimal value * $(_field_retr) * $(_field_step) @@ -108,9 +108,9 @@ $(_var(:Argument, :p)) alternatively to `f` and `∂f` a [`ManifoldSubgradientObjective`](@ref) `sgo` can be provided. -# Optional +# Keyword arguments -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * $(_kw_retraction_method_default): $(_kw_retraction_method) * `stepsize=`[`default_stepsize`](@ref)`(M, SubGradientMethodState)`: $(_kw_stepsize) which here defaults to [`ConstantStepsize`](@ref)`(M)` diff --git a/src/solvers/truncated_conjugate_gradient_descent.jl b/src/solvers/truncated_conjugate_gradient_descent.jl index ffedca6560..c179f6b372 100644 --- a/src/solvers/truncated_conjugate_gradient_descent.jl +++ b/src/solvers/truncated_conjugate_gradient_descent.jl @@ -144,7 +144,7 @@ residual. The criterion hence reads * `κ`: the reduction factor * `θ`: part of the reduction power -* $(_field_at_iteration) +$(_var(:Field, :at_iteration)) # Constructor @@ -233,7 +233,7 @@ and to end the algorithm when the trust region has been left. # Fields -* $(_field_at_iteration) +$(_var(:Field, :at_iteration)) * `trr` the trust region radius * `YPY` the computed norm of ``Y``. @@ -294,7 +294,7 @@ yield a reduction of the model. # Fields -* $(_field_at_iteration) +$(_var(:Field, :at_iteration)) * `value` store the value of the inner product. * `reason`: stores a reason of stopping if the stopping criterion has been reached, see [`get_reason`](@ref). @@ -348,7 +348,7 @@ A functor for testing if the curvature of the model value increased. # Fields -* $(_field_at_iteration) +$(_var(:Field, :at_iteration)) * `model_value`stre the last model value * `inc_model_value` store the model value that increased @@ -442,7 +442,7 @@ directly. # Keyword arguments -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * `preconditioner`: a preconditioner for the Hessian H. This is either an allocating function `(M, p, X) -> Y` or an in-place function `(M, Y, p, X) -> Y`, see `evaluation`, and by default set to the identity. diff --git a/src/solvers/trust_regions.jl b/src/solvers/trust_regions.jl index c6954857a3..d7c3d76413 100644 --- a/src/solvers/trust_regions.jl +++ b/src/solvers/trust_regions.jl @@ -10,7 +10,7 @@ Store the state of the trust-regions solver. that decides if the iteration is accepted or not. * `HX`, `HY`, `HZ`: interim storage (to avoid allocation) of ``$(_tex(:Hess)) f(p)[⋅]` of `X`, `Y`, `Z` * `max_trust_region_radius`: the maximum trust-region radius -$(_var(:Field, :p)) +$(_var(:Field, :p; comment=" storing the current iterate")) * `project!`: for numerical stability it is possible to project onto the tangent space after every iteration. the function has to work inplace of `Y`, that is `(M, Y, p, X) -> Y`, where `X` and `Y` can be the same memory. * $(_field_stop) @@ -283,7 +283,7 @@ $(_var(:Argument, :p)) * `augmentation_threshold=0.75`: trust-region augmentation threshold: if ρ is larger than this threshold, a solution is on the trust region boundary and negative curvature, and the radius is extended (augmented) * `augmentation_factor=2.0`: trust-region augmentation factor -* $(_kw_evaluation_default): $(_kw_evaluation) +$(_var(:Keyword, :evaluation)) * `κ=0.1`: the linear convergence target rate of the tCG method [`truncated_conjugate_gradient_descent`](@ref), and is used in a stopping criterion therein * `max_trust_region_radius`: the maximum trust-region radius