diff --git a/ext/ManoptManifoldsExt/ManoptManifoldsExt.jl b/ext/ManoptManifoldsExt/ManoptManifoldsExt.jl index cc4ee2b48c..1180ac6c37 100644 --- a/ext/ManoptManifoldsExt/ManoptManifoldsExt.jl +++ b/ext/ManoptManifoldsExt/ManoptManifoldsExt.jl @@ -3,11 +3,11 @@ module ManoptManifoldsExt using ManifoldsBase: exp, log, ParallelTransport, vector_transport_to using Manopt using Manopt: + _tex, + _var, _l_refl, - _l_retr, _kw_retraction_method_default, - _kw_inverse_retraction_method_default, - _kw_X_default + _kw_inverse_retraction_method_default import Manopt: max_stepsize, alternating_gradient_descent, diff --git a/ext/ManoptManifoldsExt/manifold_functions.jl b/ext/ManoptManifoldsExt/manifold_functions.jl index f921aad698..35397334cd 100644 --- a/ext/ManoptManifoldsExt/manifold_functions.jl +++ b/ext/ManoptManifoldsExt/manifold_functions.jl @@ -118,7 +118,7 @@ Reflect the point `x` from the manifold `M` at point `p`, given by $_l_refl ``` -where ``$_l_retr`` and ``$_l_retr^{-1}`` denote a retraction and an inverse +where ``$(_tex(:retr))`` and ``$(_tex(:invretr))`` denote a retraction and an inverse retraction, respectively. This can also be done in place of `q`. @@ -131,8 +131,8 @@ This can also be done in place of `q`. and for the `reflect!` additionally -* $_kw_X_default - a temporary memory to compute the inverse retraction in place. +$(_var(:Keyword, :X)) + as temporary memory to compute the inverse retraction in place. otherwise this is the memory that would be allocated anyways. """ function reflect( diff --git a/src/documentation_glossary.jl b/src/documentation_glossary.jl index e2515bae31..514b1c4977 100644 --- a/src/documentation_glossary.jl +++ b/src/documentation_glossary.jl @@ -49,11 +49,18 @@ end # --- # LaTeX -define!(:LaTeX, :Cal, (letter) -> raw"\mathcal " * "$letter") -define!(:LaTeX, :frac, (a, b) -> raw"\frac" * "{$a}{$b}") +define!(:LaTeX, :argmin, raw"\operatorname{arg\,min}") define!(:LaTeX, :bar, (letter) -> raw"\bar" * "$(letter)") 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, :Hess, raw"\operatorname{Hess}") +define!(:LaTeX, :retr, raw"\operatorname{retr}") +define!(:LaTeX, :invretr, raw"\operatorname{retr}^{-1}") +define!(:LaTeX, :text, (letter) -> raw"\text{"*"$letter"*"}") _tex(args...; kwargs...) = glossary(:LaTeX, args...; kwargs...) # --- # Mathematics and semantic symbols @@ -91,6 +98,11 @@ define!( (; M="M") -> "[`manifold_dimension`](@extref `ManifoldsBase.manifold_dimension-Tuple{AbstractManifold}`)$(length(M) > 0 ? "`($M)`" : "")", ) +define!( + :Link, + :AbstractManifold, + "[`AbstractManifold`](@extref `ManifoldsBase.AbstractManifold`)", +) # --- # Variables # in fields, keyword arguments, parameters @@ -106,8 +118,8 @@ _var(args...; kwargs...) = glossary(:Variable, args...; kwargs...) define!( :Variable, :Argument, - (s::Symbol, display="$s"; kwargs...) -> - "* `$(display)`: $(_var(s, :description;kwargs...))", + (s::Symbol, display="$s"; type=false, kwargs...) -> + "* `$(display)$(type ? "::$(_var(s, :type))" : "")`: $(_var(s, :description;kwargs...))", ) define!( :Variable, @@ -119,10 +131,28 @@ define!( :Variable, :Keyword, (s::Symbol, display="$s"; type=false, description::Bool=true, kwargs...) -> - "* `$(display)$(type ? _var(s, :type) : "")=`$(_var(s, :default;kwargs...))$(description ? ": $(_var(s, :description; kwargs...))" : "")", + "* `$(display)$(type ? "::$(_var(s, :type))" : "")=`$(_var(s, :default;kwargs...))$(description ? ": $(_var(s, :description; kwargs...))" : "")", ) # # Actual variables + +define!( + :Variable, + :f, + :description, + (; M="M", p="p") -> + "a cost function ``f: $(_tex(:Cal, M))→ ℝ`` implemented as `($M, $p) -> v`", +) + +define!( + :Variable, + :M, + :description, + (; M="M") -> + "a Riemannian manifold ``$(_tex(:Cal, M))``", +) +define!(:Variable, :M, :type, "`$(_link(:AbstractManifold))` ") + define!( :Variable, :p, :description, (; M="M") -> "a point on the manifold ``$(_tex(:Cal, M))``" ) @@ -173,14 +203,17 @@ define!( """, ) +# +# +# Stopping Criteria +define!(:StoppingCriterion, :Any, "[` | `](@ref StopWhenAny)") +define!(:StoppingCriterion, :All, "[` & `](@ref StopWhenAll)") +_sc(args...; kwargs...) = glossary(:StoppingCriterion, args...; kwargs...) + # --- # Old strings # LateX symbols -_l_ds = raw"\displaystyle" -_l_argmin = raw"\operatorname{arg\,min}" -_l_grad = raw"\operatorname{grad}" -_l_Hess = raw"\operatorname{Hess}" _l_log = raw"\log" _l_prox = raw"\operatorname{prox}" _l_refl = raw"\operatorname{refl}_p(x) = \operatorname{retr}_p(-\operatorname{retr}^{-1}_p x)" @@ -193,17 +226,12 @@ _l_Manifold(M="M") = _tex(:Cal, "M") _l_M = "$(_l_Manifold())" _l_TpM(p="p") = "T_{$p}$_l_M" _l_DΛ = "DΛ: T_{m}$(_math(:M)) → T_{Λ(m)}$(_l_Manifold("N"))" -_l_grad_long = raw"\operatorname{grad} f: \mathcal M → T\mathcal M" -_l_Hess_long = "$_l_Hess f(p)[⋅]: $(_l_TpM()) → $(_l_TpM())" -_l_retr = raw"\operatorname{retr}" -_l_retr_long = raw"\operatorname{retr}: T\mathcal M \to \mathcal M" _l_C_subset_M = "$(_tex(:Cal, "C")) ⊂ $(_tex(:Cal, "M"))" -_l_txt(s) = "\\text{$s}" # Math terms _math_VT = raw"a vector transport ``T``" -_math_inv_retr = "an inverse retraction ``$_l_retr^{-1}``" -_math_retr = " a retraction $_l_retr" +_math_inv_retr = "an inverse retraction ``$(_tex(:invretr))``" +_math_retr = " a retraction $(_tex(:retr))" _math_reflect = raw""" ```math \operatorname{refl}_p(x) = \operatorname{retr}_p(-\operatorname{retr}^{-1}_p x), @@ -241,19 +269,15 @@ the [`AbstractManifoldGradientObjective`](@ref) `gradient_objective` directly. """ # Arguments -_arg_f = raw"* `f`: a cost function ``f: \mathcal M→ℝ`` implemented as `(M, p) -> v`" _arg_grad_f = raw""" * `grad_f`: the gradient ``\operatorname{grad}f: \mathcal M → T\mathcal M`` of f as a function `(M, p) -> X` or a function `(M, X, p) -> X` computing `X` in-place """ _arg_Hess_f = """ -* `Hess_f`: the Hessian ``$_l_Hess_long`` of f +* `Hess_f`: the Hessian ``$(_tex(:Hess))_long`` of f as a function `(M, p, X) -> Y` or a function `(M, Y, p, X) -> Y` computing `Y` in-place """ -_arg_p = raw"* `p` an initial value `p` ``= p^{(0)} ∈ \mathcal M``" -_arg_M = "* `M` a manifold ``$_l_M``" _arg_inline_M = "the manifold `M`" -_arg_X = "* `X` a tangent vector" _arg_sub_problem = "* `sub_problem` a [`AbstractManoptProblem`](@ref) to specify a problem for a solver or a closed form solution function." _arg_sub_state = "* `sub_state` a [`AbstractManoptSolverState`](@ref) for the `sub_problem`." _arg_subgrad_f = raw""" @@ -270,17 +294,13 @@ The obtained approximate minimizer ``p^*``. To obtain the whole final state of the solver, see [`get_solver_return`](@ref) for details, especially the `return_state=` keyword. """ -_sc_any = "[` | `](@ref StopWhenAny)" -_sc_all = "[` & `](@ref StopWhenAll)" - # 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 ``$(_l_grad)f(p^{(k)}) ∈ T_p$(_math(:M))``" +_field_gradient = "`X`: the current gradient ``$(_tex(:grad))f(p^{(k)}) ∈ T_p$(_math(:M))``" _field_subgradient = "`X` : the current subgradient ``$(_l_subgrad)f(p^{(k)}) ∈ T_p$_l_M``" -_field_inv_retr = "`inverse_retraction_method::`[`AbstractInverseRetractionMethod`](@extref `ManifoldsBase.AbstractInverseRetractionMethod`) : an inverse retraction ``$(_l_retr)^{-1}``" -_field_p = raw"`p`, an initial value `p` ``= p^{(0)} ∈ \mathcal M``" -_field_retr = "`retraction_method::`[`AbstractRetractionMethod`](@extref `ManifoldsBase.AbstractRetractionMethod`) : a retraction ``$(_l_retr_long)``" +_field_inv_retr = "`inverse_retraction_method::`[`AbstractInverseRetractionMethod`](@extref `ManifoldsBase.AbstractInverseRetractionMethod`) : an inverse retraction ``$(_tex(:invretr))``" +_field_retr = "`retraction_method::`[`AbstractRetractionMethod`](@extref `ManifoldsBase.AbstractRetractionMethod`) : a retraction ``$(_tex(:retr))``" _field_sub_problem = "`sub_problem::Union{`[`AbstractManoptProblem`](@ref)`, F}`: a manopt problem or a function for a closed form solution of the sub problem" _field_sub_state = "`sub_state::Union{`[`AbstractManoptSolverState`](@ref)`,`[`AbstractEvaluationType`](@ref)`}`: for a sub problem state which solver to use, for the closed form solution function, indicate, whether the closed form solution function works with [`AllocatingEvaluation`](@ref)) `(M, p, X) -> q` or with an [`InplaceEvaluation`](@ref)) `(M, q, p, X) -> q`" _field_stop = "`stop::`[`StoppingCriterion`](@ref) : a functor indicating when to stop and whether the algorithm has stopped" @@ -296,7 +316,7 @@ _kw_evaluation = "specify whether the functions that return an array, for exampl _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 ``$(_l_retr)^{-1}`` to use, see [the section on retractions and their inverses](@extref ManifoldsBase :doc:`retractions`)." +_kw_inverse_retraction_method = "an inverse retraction ``$(_tex(:invretr))`` to use, see [the section on retractions and their inverses](@extref ManifoldsBase :doc:`retractions`)." _kw_others = raw""" All other keyword arguments are passed to [`decorate_state!`](@ref) for state decorators or @@ -307,7 +327,7 @@ _kw_p_default = "`p=`$(Manopt._link(:rand))" _kw_p = raw"specify an initial value for the point `p`." _kw_retraction_method_default = raw"`retraction_method=`[`default_retraction_method`](@extref `ManifoldsBase.default_retraction_method-Tuple{AbstractManifold}`)`(M, typeof(p))`" -_kw_retraction_method = "a retraction ``$(_l_retr)`` to use, see [the section on retractions](@extref ManifoldsBase :doc:`retractions`)." +_kw_retraction_method = "a retraction ``$(_tex(:retr))`` to use, see [the section on retractions](@extref ManifoldsBase :doc:`retractions`)." _kw_stepsize = raw"a functor inheriting from [`Stepsize`](@ref) to determine a step size" diff --git a/src/helpers/checks.jl b/src/helpers/checks.jl index 22e73ce674..2c4ae2e90d 100644 --- a/src/helpers/checks.jl +++ b/src/helpers/checks.jl @@ -91,7 +91,7 @@ no plot is generated. # Keyword arguments * `check_vector=true`: - verify that ``$_l_grad f(p) ∈ $(_l_TpM())`` using `is_vector`. + verify that ``$(_tex(:grad))f(p) ∈ $(_l_TpM())`` using `is_vector`. * `exactness_tol=1e-12`: if all errors are below this tolerance, the gradient is considered to be exact * `io=nothing`: @@ -170,13 +170,13 @@ no plot is generated. # Keyword arguments * `check_grad=true`: - verify that ``$_l_grad f(p) ∈ $(_l_TpM())``. + verify that ``$(_tex(:grad))f(p) ∈ $(_l_TpM())``. * `check_linearity=true`: verify that the Hessian is linear, see [`is_Hessian_linear`](@ref) using `a`, `b`, `X`, and `Y` * `check_symmetry=true`: verify that the Hessian is symmetric, see [`is_Hessian_symmetric`](@ref) * `check_vector=false`: - verify that `$_l_Hess f(p)[X] ∈ $(_l_TpM())`` using `is_vector`. + verify that `$(_tex(:Hess)) f(p)[X] ∈ $(_l_TpM())`` using `is_vector`. * `mode=:Default`: specify the mode for the verification; the default assumption is, that the retraction provided is of second order. Otherwise one can also verify the Hessian @@ -194,7 +194,7 @@ no plot is generated. * `gradient=grad_f(M, p)`: instead of the gradient function you can also provide the gradient at `p` directly * `Hessian=Hess_f(M, p, X)`: - instead of the Hessian function you can provide the result of ``$_l_Hess f(p)[X]`` directly. + instead of the Hessian function you can provide the result of ``$(_tex(:Hess)) f(p)[X]`` directly. Note that evaluations of the Hessian might still be necessary for checking linearity and symmetry and/or when using `:CriticalPoint` mode. * `limits=(1e-8,1)`: specify the limits in the `log_range` diff --git a/src/plans/augmented_lagrangian_plan.jl b/src/plans/augmented_lagrangian_plan.jl index 62c7ef4325..faaca18452 100644 --- a/src/plans/augmented_lagrangian_plan.jl +++ b/src/plans/augmented_lagrangian_plan.jl @@ -69,7 +69,7 @@ additionally this gradient does accept a positional last argument to specify the for the internal gradient call of the constrained objective. based on the internal [`ConstrainedManifoldObjective`](@ref) and computes the gradient -`$_l_grad $(_tex(:Cal, "L"))_{ρ}(p, μ, λ)``, see also [`AugmentedLagrangianCost`](@ref). +`$(_tex(:grad))$(_tex(:Cal, "L"))_{ρ}(p, μ, λ)``, see also [`AugmentedLagrangianCost`](@ref). ## Fields diff --git a/src/plans/cache.jl b/src/plans/cache.jl index 586e6167a2..098c0c2e8f 100644 --- a/src/plans/cache.jl +++ b/src/plans/cache.jl @@ -5,7 +5,7 @@ SimpleManifoldCachedObjective{O<:AbstractManifoldGradientObjective{E,TC,TG}, P, T,C} <: AbstractManifoldGradientObjective{E,TC,TG} Provide a simple cache for an [`AbstractManifoldGradientObjective`](@ref) that is for a given point `p` this cache -stores a point `p` and a gradient ``$(_l_grad) f(p)`` in `X` as well as a cost value ``f(p)`` in `c`. +stores a point `p` and a gradient ``$(_tex(:grad)) f(p)`` in `X` as well as a cost value ``f(p)`` in `c`. Both `X` and `c` are accompanied by booleans to keep track of their validity. diff --git a/src/plans/conjugate_gradient_plan.jl b/src/plans/conjugate_gradient_plan.jl index ba80709088..bd9a06c961 100644 --- a/src/plans/conjugate_gradient_plan.jl +++ b/src/plans/conjugate_gradient_plan.jl @@ -27,8 +27,8 @@ specify options for a conjugate gradient descent algorithm, that solves a # Fields -* $_field_p -* $_field_X +$(_var(:Field, :p)) +$(_var(:Field, :X)) * `δ`: the current descent direction, also a tangent vector * `β`: the current update coefficient rule, see . * `coefficient`: function to determine the new `β` @@ -52,7 +52,7 @@ The following fields from above q` performing a proximal maps, where `⁠λ` denotes the proximal parameter, for each of the summands of `F`. These can also be given in the [`InplaceEvaluation`](@ref) variants `(M, q, λ p) -> q` computing in place of `q`. -$(_arg_p) +$(_var(:Argument, :p)) # Keyword arguments @@ -189,7 +189,7 @@ $(_arg_p) * `reflection_evaluation`: ([`AllocatingEvaluation`](@ref) whether `R` works in-place or allocating * $(_kw_retraction_method_default): $(_kw_retraction_method) This is used both in the relaxation step as well as in the reflection, unless you set `R` yourself. -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc_any)[`StopWhenChangeLess`](@ref)`(1e-5)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-5)`: $(_kw_stopping_criterion) * `parallel=false`: indicate whether to use a parallel Douglas-Rachford or not. diff --git a/src/solvers/FrankWolfe.jl b/src/solvers/FrankWolfe.jl index 23fbc3e35c..dd600f7275 100644 --- a/src/solvers/FrankWolfe.jl +++ b/src/solvers/FrankWolfe.jl @@ -39,7 +39,7 @@ Initialise the Frank Wolfe method state, where `sub_problem` is a closed form so ## Input -$_arg_M +$(_var(:Argument, :M; type=true)) $_arg_sub_problem $_arg_sub_state @@ -48,7 +48,7 @@ $_arg_sub_state * $(_kw_p_default): $(_kw_p) * $(_kw_inverse_retraction_method_default): $(_kw_inverse_retraction_method) * $(_kw_retraction_method_default): $(_kw_retraction_method) -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$_sc_any[`StopWhenGradientNormLess`](@ref)`(1e-6)` $_kw_stop_note +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-6)` $_kw_stop_note * `stepsize=`[`default_stepsize`](@ref)`(M, FrankWolfeState)` * $(_kw_X_default): $(_kw_X) @@ -183,10 +183,10 @@ use a retraction and its inverse. # Input -$_arg_M -$_arg_f +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $_arg_grad_f -$_arg_p +$(_var(:Argument, :p)) $_arg_alt_mgo @@ -201,11 +201,11 @@ $_arg_alt_mgo * `stepsize=`[`DecreasingStepsize`](@ref)`(; length=2.0, shift=2)`: $_kw_stepsize, where the default is the step size $_doc_FW_sk_default -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(500)`$_sc_any[`StopWhenGradientNormLess`](@ref)`(1.0e-6)`) +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(500)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1.0e-6)`) $_kw_stopping_criterion * $_kw_X_default: - $_kw_X, the evaluated gradient ``$_l_grad f`` evaluated at ``p^{(k)}``. + $_kw_X, the evaluated gradient ``$(_tex(:grad))f`` evaluated at ``p^{(k)}``. * `sub_cost=`[`FrankWolfeCost`](@ref)`(p, X)`: the cost of the Frank-Wolfe sub problem. $(_kw_used_in("sub_objective")) @@ -231,7 +231,7 @@ $_arg_alt_mgo specify either the solver for a `sub_problem` or the kind of evaluation if the sub problem is given by a closed form solution this keyword takes into account the `sub_stopping_criterion`, and the `sub_kwargs`, that are also used to potentially decorate the state. -* `sub_stopping_criterion=`[`StopAfterIteration`](@ref)`(300)`$_sc_any[`StopWhenStepsizeLess`](@ref)`(1e-8)`: +* `sub_stopping_criterion=`[`StopAfterIteration`](@ref)`(300)`$(_sc(:Any))[`StopWhenStepsizeLess`](@ref)`(1e-8)`: $_kw_stopping_criterion for the sub solver. $(_kw_used_in("sub_state")) $_kw_others diff --git a/src/solvers/Lanczos.jl b/src/solvers/Lanczos.jl index 548b0d3890..2125ecbfd5 100644 --- a/src/solvers/Lanczos.jl +++ b/src/solvers/Lanczos.jl @@ -29,7 +29,7 @@ Solve the adaptive regularized subproblem with a Lanczos iteration * $_kw_X_default: the iterate using the manifold of the tangent space. * `maxIterLanzcos=200`: shortcut to set the maximal number of iterations in the ` stopping_crtierion=` * `θ=0.5`: set the parameter in the [`StopWhenFirstOrderProgress`](@ref) within the default `stopping_criterion=`. -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(maxIterLanczos)`$_sc_any[`StopWhenFirstOrderProgress`](@ref)`(θ)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(maxIterLanczos)`$(_sc(:Any))[`StopWhenFirstOrderProgress`](@ref)`(θ)`: the stopping criterion for the Lanczos iteration. * `stopping_criterion_newtown=`[`StopAfterIteration`](@ref)`(200)`: the stopping criterion for the inner Newton iteration. * `σ=10.0`: specify the regularization parameter diff --git a/src/solvers/LevenbergMarquardt.jl b/src/solvers/LevenbergMarquardt.jl index 47351a32bc..8bda96aae1 100644 --- a/src/solvers/LevenbergMarquardt.jl +++ b/src/solvers/LevenbergMarquardt.jl @@ -18,12 +18,12 @@ The second signature performs the optimization in-place of `p`. # Input -$(_arg_M) +$(_var(:Argument, :M; type=true)) * `f`: a cost function ``f: $(_math(:M)) M→ℝ^d`` * `jacobian_f`: the Jacobian of ``f``. The Jacobian is supposed to accept a keyword argument `basis_domain` which specifies basis of the tangent space at a given point in which the Jacobian is to be calculated. By default it should be the `DefaultOrthonormalBasis`. -$(_arg_p) +$(_var(:Argument, :p)) * `num_components`: length of the vector returned by the cost function (`d`). By default its value is -1 which means that it is determined automatically by calling `f` one additional time. This is only possible when `evaluation` is `AllocatingEvaluation`, @@ -47,7 +47,7 @@ then the keyword `jacobian_tangent_basis` below is ignored By default this is a vector of length `num_components` of similar type as `p`. * `jacobian_tangent_basis`: an [`AbstractBasis`](@extref `ManifoldsBase.AbstractBasis`) specify the basis of the tangent space for `jacobian_f`. * $(_kw_retraction_method_default): $(_kw_retraction_method) -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-12)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-12)`: $(_kw_others) diff --git a/src/solvers/NelderMead.jl b/src/solvers/NelderMead.jl index 143983b6a5..590f99cfef 100644 --- a/src/solvers/NelderMead.jl +++ b/src/solvers/NelderMead.jl @@ -81,7 +81,7 @@ Construct a Nelder-Mead Option with a default population (if not provided) of se # Keyword arguments * `population=`[`NelderMeadSimplex`](@ref)`(M)` -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(2000)`$_sc_any[`StopWhenPopulationConcentrated`](@ref)`()`): +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(2000)`$(_sc(:Any))[`StopWhenPopulationConcentrated`](@ref)`()`): a [`StoppingCriterion`](@ref) * `α=1.0`: reflection parameter ``α > 0``: * `γ=2.0` expansion parameter ``γ``: @@ -191,21 +191,21 @@ points is chosen. The compuation can be performed in-place of the `population`. The algorithm consists of the following steps. Let ``d`` denote the dimension of the manifold ``$_l_M``. 1. Order the simplex vertices ``p_i, i=1,…,d+1`` by increasing cost, such that we have ``f(p_1) ≤ f(p_2) ≤ … ≤ f(p_{d+1})``. -2. Compute the Riemannian center of mass [Karcher:1977](@cite), cf. [`mean`](@extref Statistics.mean-Tuple{AbstractManifold, Vararg{Any}}), ``p_{$(_l_txt("m"))}`` +2. Compute the Riemannian center of mass [Karcher:1977](@cite), cf. [`mean`](@extref Statistics.mean-Tuple{AbstractManifold, Vararg{Any}}), ``p_{$(_tex(:text, "m"))}`` of the simplex vertices ``p_1,…,p_{d+1}``. -3. Reflect the point with the worst point at the mean ``p_{$(_l_txt("r"))} = $(_l_retr)_{p_{$(_l_txt("m"))}}\\bigl( - α$(_l_retr)^{-1}_{p_{$(_l_txt("m"))}} (p_{d+1}) \\bigr)`` - If ``f(p_1) ≤ f(p_{$(_l_txt("r"))}) ≤ f(p_{d})`` then set ``p_{d+1} = p_{$(_l_txt("r"))}`` and go to step 1. -4. Expand the simplex if ``f(p_{$(_l_txt("r"))}) < f(p_1)`` by computing the expantion point ``p_{$(_l_txt("e"))} = $(_l_retr)_{p_{$(_l_txt("m"))}}\\bigl( - γα$(_l_retr)^{-1}_{p_{$(_l_txt("m"))}} (p_{d+1}) \\bigr)``, +3. Reflect the point with the worst point at the mean ``p_{$(_tex(:text, "r"))} = $(_tex(:retr))_{p_{$(_tex(:text, "m"))}}\\bigl( - α$(_tex(:invretr))_{p_{$(_tex(:text, "m"))}} (p_{d+1}) \\bigr)`` + If ``f(p_1) ≤ f(p_{$(_tex(:text, "r"))}) ≤ f(p_{d})`` then set ``p_{d+1} = p_{$(_tex(:text, "r"))}`` and go to step 1. +4. Expand the simplex if ``f(p_{$(_tex(:text, "r"))}) < f(p_1)`` by computing the expantion point ``p_{$(_tex(:text, "e"))} = $(_tex(:retr))_{p_{$(_tex(:text, "m"))}}\\bigl( - γα$(_tex(:invretr))_{p_{$(_tex(:text, "m"))}} (p_{d+1}) \\bigr)``, which in this formulation allows to reuse the tangent vector from the inverse retraction from before. - If ``f(p_{$(_l_txt("e"))}) < f(p_{$(_l_txt("r"))})`` then set ``p_{d+1} = p_{$(_l_txt("e"))}`` otherwise set set ``p_{d+1} = p_{$(_l_txt("r"))}``. Then go to Step 1. -5. Contract the simplex if ``f(p_{$(_l_txt("r"))}) ≥ f(p_d)``. - 1. If ``f(p_{$(_l_txt("r"))}) < f(p_{d+1})`` set the step ``s = -ρ`` + If ``f(p_{$(_tex(:text, "e"))}) < f(p_{$(_tex(:text, "r"))})`` then set ``p_{d+1} = p_{$(_tex(:text, "e"))}`` otherwise set set ``p_{d+1} = p_{$(_tex(:text, "r"))}``. Then go to Step 1. +5. Contract the simplex if ``f(p_{$(_tex(:text, "r"))}) ≥ f(p_d)``. + 1. If ``f(p_{$(_tex(:text, "r"))}) < f(p_{d+1})`` set the step ``s = -ρ`` 2. otherwise set ``s=ρ``. - Compute the contraction point ``p_{$(_l_txt("c"))} = $(_l_retr)_{p_{$(_l_txt("m"))}}\\bigl(s$(_l_retr)^{-1}_{p_{$(_l_txt("m"))}} p_{d+1} \\bigr)``. - 1. in this case if ``f(p_{$(_l_txt("c"))}) < f(p_{$(_l_txt("r"))})`` set ``p_{d+1} = p_{$(_l_txt("c"))}`` and go to step 1 - 2. in this case if ``f(p_{$(_l_txt("c"))}) < f(p_{d+1})`` set ``p_{d+1} = p_{$(_l_txt("c"))}`` and go to step 1 + Compute the contraction point ``p_{$(_tex(:text, "c"))} = $(_tex(:retr))_{p_{$(_tex(:text, "m"))}}\\bigl(s$(_tex(:invretr))_{p_{$(_tex(:text, "m"))}} p_{d+1} \\bigr)``. + 1. in this case if ``f(p_{$(_tex(:text, "c"))}) < f(p_{$(_tex(:text, "r"))})`` set ``p_{d+1} = p_{$(_tex(:text, "c"))}`` and go to step 1 + 2. in this case if ``f(p_{$(_tex(:text, "c"))}) < f(p_{d+1})`` set ``p_{d+1} = p_{$(_tex(:text, "c"))}`` and go to step 1 6. Shrink all points (closer to ``p_1``). For all ``i=2,...,d+1`` set - ``p_{i} = $(_l_retr)_{p_{1}}\\bigl( σ$(_l_retr)^{-1}_{p_{1}} p_{i} \\bigr).`` + ``p_{i} = $(_tex(:retr))_{p_{1}}\\bigl( σ$(_tex(:invretr))_{p_{1}} p_{i} \\bigr).`` For more details, see The Euclidean variant in the Wikipedia [https://en.wikipedia.org/wiki/Nelder-Mead_method](https://en.wikipedia.org/wiki/Nelder-Mead_method) @@ -213,14 +213,14 @@ or Algorithm 4.1 in [http://www.optimization-online.org/DB_FILE/2007/08/1742.pdf # Input -$_arg_M -$_arg_f +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) * `population::`[`NelderMeadSimplex`](@ref)`=`[`NelderMeadSimplex`](@ref)`(M)`: an initial simplex of ``d+1`` points, where ``d`` is the $(_link(:manifold_dimension; M="")) of `M`. # Keyword arguments -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(2000)`$_sc_any[`StopWhenPopulationConcentrated`](@ref)`()`): +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(2000)`$(_sc(:Any))[`StopWhenPopulationConcentrated`](@ref)`()`): a [`StoppingCriterion`](@ref) * `α=1.0`: reflection parameter ``α > 0``: * `γ=2.0` expansion parameter ``γ``: diff --git a/src/solvers/adaptive_regularization_with_cubics.jl b/src/solvers/adaptive_regularization_with_cubics.jl index 433fe540e1..269621a71c 100644 --- a/src/solvers/adaptive_regularization_with_cubics.jl +++ b/src/solvers/adaptive_regularization_with_cubics.jl @@ -209,7 +209,7 @@ Let ``Xp^{(k)}`` denote the minimizer of the model ``m_k`` and use the model imp $_doc_ARC_improvement With two thresholds ``η_2 ≥ η_1 > 0`` -set ``p_{k+1} = $(_l_retr)_{p_k}(X_k)`` if ``ρ ≥ η_1`` +set ``p_{k+1} = $(_tex(:retr))_{p_k}(X_k)`` if ``ρ ≥ η_1`` and reject the candidate otherwise, that is, set ``p_{k+1} = p_k``. Further update the regularization parameter using factors ``0 < γ_1 < 1 < γ_2`` reads @@ -220,11 +220,11 @@ For more details see [AgarwalBoumalBullinsCartis:2020](@cite). # Input -$_arg_M -$_arg_f +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $_arg_grad_f $_arg_Hess_f -$_arg_p +$(_var(:Argument, :p)) the cost `f` and its gradient and Hessian might also be provided as a [`ManifoldHessianObjective`](@ref) @@ -243,7 +243,7 @@ the cost `f` and its gradient and Hessian might also be provided as a [`Manifold * `ρ_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 b2a37377fc..484dbc17a6 100644 --- a/src/solvers/alternating_gradient_descent.jl +++ b/src/solvers/alternating_gradient_descent.jl @@ -160,12 +160,12 @@ perform an alternating gradient descent. This can be done in-place of the start # Input -$_arg_M -$_arg_f +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) * `grad_f`: a gradient, that can be of two cases * is a single function returning an `ArrayPartition` or * is a vector functions each returning a component part of the whole gradient -$_arg_p +$(_var(:Argument, :p)) # Keyword arguments diff --git a/src/solvers/augmented_Lagrangian_method.jl b/src/solvers/augmented_Lagrangian_method.jl index 1c996cc476..4f52e5e862 100644 --- a/src/solvers/augmented_Lagrangian_method.jl +++ b/src/solvers/augmented_Lagrangian_method.jl @@ -2,7 +2,7 @@ # State # -_sc_alm_default = "[`StopAfterIteration`](@ref)`(300)`$_sc_any([`StopWhenSmallerOrEqual](@ref)`(:ϵ, ϵ_min)`$_sc_all[`StopWhenChangeLess`](@ref)`(1e-10) )$_sc_any[`StopWhenChangeLess`](@ref)`" +_sc_alm_default = "[`StopAfterIteration`](@ref)`(300)`$(_sc(:Any))([`StopWhenSmallerOrEqual](@ref)`(:ϵ, ϵ_min)`$(_sc(:All))[`StopWhenChangeLess`](@ref)`(1e-10) )$(_sc(:Any))[`StopWhenChangeLess`](@ref)`" @doc """ AugmentedLagrangianMethodState{P,T} <: AbstractManoptSolverState @@ -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 -* $_field_p +$(_var(:Field, :p)) * `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 @@ -267,8 +267,8 @@ where ``θ_ρ ∈ (0,1)`` is a constant scaling factor. # Input -$_arg_M -$_arg_f +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $_arg_grad_f # Optional (if not called with the [`ConstrainedManifoldObjective`](@ref) `cmo`) diff --git a/src/solvers/conjugate_gradient_descent.jl b/src/solvers/conjugate_gradient_descent.jl index 7a23151be3..658985f2b4 100644 --- a/src/solvers/conjugate_gradient_descent.jl +++ b/src/solvers/conjugate_gradient_descent.jl @@ -49,9 +49,9 @@ perform a conjugate gradient based descent- $(_doc_CG_formula) -where ``$(_l_retr)`` denotes a retraction on the `Manifold` `M` +where ``$(_tex(:retr))`` denotes a retraction on the `Manifold` `M` and one can employ different rules to update the descent direction ``δ_k`` based on -the last direction ``δ_{k-1}`` and both gradients ``$(_l_grad)f(x_k)``,``$(_l_grad) f(x_{k-1})``. +the last direction ``δ_{k-1}`` and both gradients ``$(_tex(:grad))f(x_k)``,``$(_tex(:grad)) f(x_{k-1})``. The [`Stepsize`](@ref) ``s_k`` may be determined by a [`Linesearch`](@ref). Alternatively to `f` and `grad_f` you can provide @@ -69,10 +69,10 @@ $(_doc_update_delta_k) # Input -$(_arg_M) -$(_arg_f) +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $(_arg_grad_f) -$(_arg_p) +$(_var(:Argument, :p)) # Keyword arguments @@ -84,7 +84,7 @@ $(_arg_p) * $(_kw_retraction_method_default): $(_kw_retraction_method) * `stepsize=[`ArmijoLinesearch`](@ref)`(M)`: $_kw_stepsize via [`default_stepsize`](@ref)) passing on the `default_retraction_method` -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(500)`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-8)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(500)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-8)`: $(_kw_stopping_criterion) * $(_kw_vector_transport_method_default): $(_kw_vector_transport_method) diff --git a/src/solvers/conjugate_residual.jl b/src/solvers/conjugate_residual.jl index 9dddc0b1e7..6290133064 100644 --- a/src/solvers/conjugate_residual.jl +++ b/src/solvers/conjugate_residual.jl @@ -20,11 +20,11 @@ is initalised with ``X^{(0)}`` as the zero vector and performed the following steps at iteration ``k=0,…`` until the `stopping_criterion` is fulfilled. -1. compute a step size ``α_k = $(_l_ds)$(_tex(:frac, "⟨ r^{(k)}, $(_tex(:Cal, "A"))(p)[r^{(k)}] ⟩_p","⟨ $(_tex(:Cal, "A"))(p)[d^{(k)}], $(_tex(:Cal, "A"))(p)[d^{(k)}] ⟩_p"))`` +1. compute a step size ``α_k = $(_tex(:displaystyle))$(_tex(:frac, "⟨ r^{(k)}, $(_tex(:Cal, "A"))(p)[r^{(k)}] ⟩_p","⟨ $(_tex(:Cal, "A"))(p)[d^{(k)}], $(_tex(:Cal, "A"))(p)[d^{(k)}] ⟩_p"))`` 2. do a step ``X^{(k+1)} = X^{(k)} + α_kd^{(k)}`` 2. update the residual ``r^{(k+1)} = r^{(k)} + α_k Y^{(k)}`` 4. compute ``Z = $(_tex(:Cal, "A"))(p)[r^{(k+1)}]`` -5. Update the conjugate coefficient ``β_k = $(_l_ds)$(_tex(:frac, "⟨ r^{(k+1)}, $(_tex(:Cal, "A"))(p)[r^{(k+1)}] ⟩_p", "⟨ r^{(k)}, $(_tex(:Cal, "A"))(p)[r^{(k)}] ⟩_p"))`` +5. Update the conjugate coefficient ``β_k = $(_tex(:displaystyle))$(_tex(:frac, "⟨ r^{(k+1)}, $(_tex(:Cal, "A"))(p)[r^{(k+1)}] ⟩_p", "⟨ r^{(k)}, $(_tex(:Cal, "A"))(p)[r^{(k)}] ⟩_p"))`` 6. Update the conjugate direction ``d^{(k+1)} = r^{(k+1)} + β_kd^{(k)}`` 7. Update ``Y^{(k+1)} = -Z + β_k Y^{(k)}`` @@ -40,7 +40,7 @@ Note that the right hand side of Step 7 is the same as evaluating ``$(_tex(:Cal, # Keyword arguments * `evaluation=`[`AllocatingEvaluation`](@ref) specify whether `A` and `b` are implemented allocating or in-place -* `stopping_criterion::`[`StoppingCriterion`](@ref)`=`[`StopAfterIteration`](@ref)`(`$(_link(:manifold_dimension))$_sc_any[`StopWhenRelativeResidualLess`](@ref)`(c,1e-8)`, +* `stopping_criterion::`[`StoppingCriterion`](@ref)`=`[`StopAfterIteration`](@ref)`(`$(_link(:manifold_dimension))$(_sc(:Any))[`StopWhenRelativeResidualLess`](@ref)`(c,1e-8)`, where `c` is the norm of ``$(_l_norm("b"))``. # Output diff --git a/src/solvers/convex_bundle_method.jl b/src/solvers/convex_bundle_method.jl index dd61f1dafa..dfa865badc 100644 --- a/src/solvers/convex_bundle_method.jl +++ b/src/solvers/convex_bundle_method.jl @@ -42,7 +42,7 @@ Generate the state for the [`convex_bundle_method`](@ref) on the manifold `M` ## Input -$_arg_M +$(_var(:Argument, :M; type=true)) $_arg_sub_problem $_arg_sub_state @@ -61,7 +61,7 @@ Most of the following keyword arguments set default values for the fields mentio * `stepsize=default_stepsize(M, ConvexBundleMethodState)`, which defaults to [`ConstantStepsize`](@ref)`(M)`. * $(_kw_inverse_retraction_method_default): $(_kw_inverse_retraction_method) * $(_kw_retraction_method_default): $(_kw_retraction_method) -* `stopping_criterion=`[`StopWhenLagrangeMultiplierLess`](@ref)`(1e-8)`$(_sc_any)[`StopAfterIteration`](@ref)`(5000)` +* `stopping_criterion=`[`StopWhenLagrangeMultiplierLess`](@ref)`(1e-8)`$(_sc(:Any))[`StopAfterIteration`](@ref)`(5000)` * `X=`$(_link(:zero_vector)) specify the type of tangent vector to use. * $(_kw_vector_transport_method_default): $(_kw_vector_transport_method) * `sub_problem=`[`convex_bundle_method_subsolver`](@ref) @@ -283,7 +283,7 @@ _doc_convex_bundle_method = """ convex_bundle_method(M, f, ∂f, p) convex_bundle_method!(M, f, ∂f, p) -perform a convex bundle method ``p^{(k+1)} = $(_l_retr)_{p^{(k)}}(-g_k)`` where +perform a convex bundle method ``p^{(k+1)} = $(_tex(:retr))_{p^{(k)}}(-g_k)`` where $(_doc_cbm_gk) @@ -297,10 +297,10 @@ For more details, see [BergmannHerzogJasa:2024](@cite). # Input -$(_arg_M) -$(_arg_f) +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $(_arg_subgrad_f) -$(_arg_p) +$(_var(:Argument, :p)) # Keyword arguments @@ -315,7 +315,7 @@ $(_arg_p) * `stepsize=default_stepsize(M, ConvexBundleMethodState)`, which defaults to [`ConstantStepsize`](@ref)`(M)`. * $(_kw_inverse_retraction_method_default): $(_kw_inverse_retraction_method) * $(_kw_retraction_method_default): $(_kw_retraction_method) -* `stopping_criterion=`[`StopWhenLagrangeMultiplierLess`](@ref)`(1e-8)`$(_sc_any)[`StopAfterIteration`](@ref)`(5000)`: +* `stopping_criterion=`[`StopWhenLagrangeMultiplierLess`](@ref)`(1e-8)`$(_sc(:Any))[`StopAfterIteration`](@ref)`(5000)`: $(_kw_stopping_criterion) * `X=`$(_link(:zero_vector)) specify the type of tangent vector to use. * $(_kw_vector_transport_method_default): $(_kw_vector_transport_method) diff --git a/src/solvers/cyclic_proximal_point.jl b/src/solvers/cyclic_proximal_point.jl index 4fad95b5ec..f2268eca6c 100644 --- a/src/solvers/cyclic_proximal_point.jl +++ b/src/solvers/cyclic_proximal_point.jl @@ -25,7 +25,7 @@ perform a cyclic proximal point algorithm. This can be done in-place of `p`. # Input -$(_arg_M) +$(_var(:Argument, :M; type=true)) * `f`: a cost function ``f: $(_math(:M)) M→ℝ`` to minimize * `proxes_f`: an Array of proximal maps (`Function`s) `(M,λ,p) -> q` or `(M, q, λ, p) -> q` for the summands of ``f`` (see `evaluation`) @@ -37,7 +37,7 @@ where `f` and the proximal maps `proxes_f` can also be given directly as a [`Man * `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`` -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(5000)`$(_sc_any)[`StopWhenChangeLess`](@ref)`(1e-12)`): $(_kw_stopping_criterion) +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(5000)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-12)`): $(_kw_stopping_criterion) $(_kw_others) diff --git a/src/solvers/difference-of-convex-proximal-point.jl b/src/solvers/difference-of-convex-proximal-point.jl index 66767b09d6..8d6f95bf1b 100644 --- a/src/solvers/difference-of-convex-proximal-point.jl +++ b/src/solvers/difference-of-convex-proximal-point.jl @@ -33,7 +33,7 @@ construct an difference of convex proximal point state, where `sub_problem` is a ## Input -$_arg_M +$(_var(:Argument, :M; type=true)) $_arg_sub_problem $_arg_sub_state @@ -161,7 +161,7 @@ _doc_DCPPA = """ Compute the difference of convex proximal point algorithm [SouzaOliveira:2015](@cite) to minimize ```math - $(_l_argmin)_{p∈$(_math(:M))} g(p) - h(p) + $(_tex(:argmin))_{p∈$(_math(:M))} g(p) - h(p) ``` where you have to provide the subgradient ``∂h`` of ``h`` and either @@ -172,12 +172,12 @@ where you have to provide the subgradient ``∂h`` of ``h`` and either This algorithm performs the following steps given a start point `p`= ``p^{(0)}``. Then repeat for ``k=0,1,…`` -1. ``X^{(k)} ∈ $(_l_grad) h(p^{(k)})`` -2. ``q^{(k)} = $(_l_retr)_{p^{(k)}}(λ_kX^{(k)})`` +1. ``X^{(k)} ∈ $(_tex(:grad)) h(p^{(k)})`` +2. ``q^{(k)} = $(_tex(:retr))_{p^{(k)}}(λ_kX^{(k)})`` 3. ``r^{(k)} = $(_l_prox)_{λ_kg}(q^{(k)})`` -4. ``X^{(k)} = $(_l_retr)^{-1}_{p^{(k)}}(r^{(k)})`` +4. ``X^{(k)} = $(_tex(:invretr))_{p^{(k)}}(r^{(k)})`` 5. Compute a stepsize ``s_k`` and -6. set ``p^{(k+1)} = $(_l_retr)_{p^{(k)}}(s_kX^{(k)})``. +6. set ``p^{(k+1)} = $(_tex(:retr))_{p^{(k)}}(s_kX^{(k)})``. until the `stopping_criterion` is fulfilled. @@ -191,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) -* `gradient=nothing`: specify ``$(_l_grad) f``, for debug / analysis +* `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 * `g=nothing`: specify the function `g`. @@ -199,9 +199,9 @@ DC functions is obtained for ``s_k = 1`` and one can hence employ usual line sea * $(_kw_inverse_retraction_method_default); $(_kw_inverse_retraction_method) * $(_kw_retraction_method_default); $(_kw_retraction_method) * `stepsize=`[`ConstantStepsize`](@ref)`(M)`): $(_kw_stepsize) -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc_any)[`StopWhenChangeLess`](@ref)`(1e-8)`): +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-8)`): $(_kw_stopping_criterion) - A [`StopWhenGradientNormLess`](@ref)`(1e-8)` is added with $(_sc_any), when a `gradient` is provided. + A [`StopWhenGradientNormLess`](@ref)`(1e-8)` is added with $(_sc(:Any)), when a `gradient` is provided. * `sub_cost=`[`ProximalDCCost`](@ref)`(g, copy(M, p), λ(1))`): cost to be used within the default `sub_problem` that is initialized as soon as `g` is provided. $(_kw_used_in("sub_objective")) @@ -222,7 +222,7 @@ DC functions is obtained for ``s_k = 1`` and one can hence employ usual line sea By default this is also decorated using the `sub_kwargs`. if the `sub_problem` if a function (a closed form solution), this is set to `evaluation` and can be changed to the evaluation type of the closed form solution accordingly. -* `sub_stopping_criterion`: ([`StopAfterIteration`](@ref)`(300)`$(_sc_any)`[`StopWhenGradientNormLess`](@ref)`(1e-8)`: +* `sub_stopping_criterion`: ([`StopAfterIteration`](@ref)`(300)`$(_sc(:Any))`[`StopWhenGradientNormLess`](@ref)`(1e-8)`: a stopping criterion used withing the default `sub_state=` $(_kw_used_in("sub_state")) diff --git a/src/solvers/difference_of_convex_algorithm.jl b/src/solvers/difference_of_convex_algorithm.jl index c2bc671c07..091d89c2df 100644 --- a/src/solvers/difference_of_convex_algorithm.jl +++ b/src/solvers/difference_of_convex_algorithm.jl @@ -17,7 +17,7 @@ It comes in two forms, depending on the realisation of the `subproblem`. The sub task consists of a method to solve ```math - $(_l_argmin)_{q∈$(_math(:M))}\\ g(p) - ⟨X, $(_l_log)_p q⟩ + $(_tex(:argmin))_{q∈$(_math(:M))}\\ g(p) - ⟨X, $(_l_log)_p q⟩ ``` is needed. Besides a problem and a state, one can also provide a function and @@ -116,7 +116,7 @@ _doc_DoC = """ Compute the difference of convex algorithm [BergmannFerreiraSantosSouza:2023](@cite) to minimize ```math - $(_l_argmin)_{p∈$(_math(:M))}\\ g(p) - h(p) + $(_tex(:argmin))_{p∈$(_math(:M))}\\ g(p) - h(p) ``` where you need to provide ``f(p) = g(p) - h(p)``, ``g`` and the subdifferential ``∂h`` of ``h``. @@ -127,7 +127,7 @@ Then repeat for ``k=0,1,…`` 1. Take ``X^{(k)} ∈ ∂h(p^{(k)})`` 2. Set the next iterate to the solution of the subproblem ```math - p^{(k+1)} ∈ $(_l_argmin)_{q ∈ $(_math(:M))} g(q) - ⟨X^{(k)}, $(_l_log)_{p^{(k)}}q⟩ + p^{(k+1)} ∈ $(_tex(:argmin))_{q ∈ $(_math(:M))} g(q) - ⟨X^{(k)}, $(_l_log)_{p^{(k)}}q⟩ ``` until the stopping criterion (see the `stopping_criterion` keyword is fulfilled. @@ -135,9 +135,9 @@ until the stopping criterion (see the `stopping_criterion` keyword is fulfilled. # Keyword arguments * $(_kw_evaluation_default): $(_kw_evaluation) -* `gradient=nothing`: specify ``$(_l_grad) f``, for debug / analysis or enhancing the `stopping_criterion=` +* `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)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-8)`: $(_kw_stopping_criterion) * `g=nothing`: specify the function `g` If specified, a subsolver is automatically set up. * `sub_cost=`[`LinearizedDCCost`](@ref)`(g, p, initial_vector)`: a cost to be used within the default `sub_problem`. @@ -160,7 +160,7 @@ until the stopping criterion (see the `stopping_criterion` keyword is fulfilled. By default this is also decorated using the `sub_kwargs`. if the `sub_problem` if a function (a closed form solution), this is set to `evaluation` and can be changed to the evaluation type of the closed form solution accordingly. -* `sub_stopping_criterion=`[`StopAfterIteration`](@ref)`(300)`$(_sc_any)[`StopWhenStepsizeLess`](@ref)`(1e-9)`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-9)`: +* `sub_stopping_criterion=`[`StopAfterIteration`](@ref)`(300)`$(_sc(:Any))[`StopWhenStepsizeLess`](@ref)`(1e-9)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-9)`: a stopping criterion used withing the default `sub_state=` $(_kw_used_in("sub_state")) * `sub_stepsize=`[`ArmijoLinesearch`](@ref)`(M)`) specify a step size used within the `sub_state`. diff --git a/src/solvers/exact_penalty_method.jl b/src/solvers/exact_penalty_method.jl index 2d793a2faf..3ecc038366 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 -* $(_field_p) +$(_var(:Field, :p)) * `ρ`: the penalty parameter * $(_field_sub_problem) * $(_field_sub_state) @@ -43,8 +43,8 @@ construct the exact penalty state, where `sub_problem` is a closed form solution * $(_kw_p_default): $(_kw_p) * `ρ=1.0` * `θ_ρ=0.3` -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(300)`$(_sc_any)` (` - [`StopWhenSmallerOrEqual`](@ref)`(:ϵ, ϵ_min)`$(_sc_any)[`StopWhenChangeLess`](@ref)`(1e-10) )` +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(300)`$(_sc(:Any))` (` + [`StopWhenSmallerOrEqual`](@ref)`(:ϵ, ϵ_min)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-10) )` # See also @@ -212,10 +212,10 @@ $(_doc_EMP_ρ_update) # Input -$(_arg_M) -$(_arg_f) +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $(_arg_grad_f) -$(_arg_p) +$(_var(:Argument, :p)) # Keyword arguments if not called with the [`ConstrainedManifoldObjective`](@ref) `cmo` @@ -253,11 +253,11 @@ Otherwise the problem is not constrained and a better solver would be for exampl * `sub_grad=`[`ExactPenaltyGrad`](@ref)`(problem, ρ, u; smoothing=smoothing)`: gradient to use in the sub solver $(_kw_used_in("sub_problem")) * * $(_kw_sub_kwargs_default): $(_kw_sub_kwargs) -* `sub_stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(ϵ)`$(_sc_any)[`StopWhenStepsizeLess`](@ref)`(1e-10)`: a stopping cirterion for the sub solver +* `sub_stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(ϵ)`$(_sc(:Any))[`StopWhenStepsizeLess`](@ref)`(1e-10)`: a stopping cirterion for the sub solver $(_kw_used_in("sub_state")) * `sub_problem=`[`DefaultManoptProblem`](@ref)`(M, `[`ManifoldGradientObjective`](@ref)`(sub_cost, sub_grad; evaluation=evaluation)`: the problem for the subsolver. The objective can also be decorated with argumens from `sub_kwargs`. * `sub_state=`[`QuasiNewtonState`](@ref)`(...)` a solver to use for the sub problem. By default an L-BFGS is used. -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(300)`$(_sc_any)` ( `[`StopWhenSmallerOrEqual`](@ref)`(ϵ, ϵ_min)`$(_sc_all)[`StopWhenChangeLess`](@ref)`(1e-10) )`: $(_kw_stopping_criterion) +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(300)`$(_sc(:Any))` ( `[`StopWhenSmallerOrEqual`](@ref)`(ϵ, ϵ_min)`$(_sc(:All))[`StopWhenChangeLess`](@ref)`(1e-10) )`: $(_kw_stopping_criterion) For the `range`s of the constraints' gradient, other power manifold tangent space representations, mainly the [`ArrayPowerRepresentation`](@extref Manifolds :jl:type:`Manifolds.ArrayPowerRepresentation`) can be used if the gradients can be computed more efficiently in that representation. diff --git a/src/solvers/gradient_descent.jl b/src/solvers/gradient_descent.jl index a3d347a80a..dd16a94f04 100644 --- a/src/solvers/gradient_descent.jl +++ b/src/solvers/gradient_descent.jl @@ -22,7 +22,7 @@ Initialize the gradient descent solver state, where ## Input -$_arg_M +$(_var(:Argument, :M; type=true)) ## Keyword arguments @@ -129,10 +129,10 @@ The algorithm can be performed in-place of `p`. # Input -$_arg_M -$_arg_f +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $_arg_grad_f -$_arg_p +$(_var(:Argument, :p)) $_arg_alt_mgo @@ -151,11 +151,11 @@ $_arg_alt_mgo * `stepsize=`[`default_stepsize`](@ref)`(M, GradientDescentState)`: $_kw_stepsize -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$_sc_any[`StopWhenGradientNormLess`](@ref)`(1e-8)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(200)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-8)`: $_kw_stopping_criterion * $_kw_X_default: - $_kw_X, the evaluated gradient ``$_l_grad f`` evaluated at ``p^{(k)}``. + $_kw_X, the evaluated gradient ``$(_tex(:grad))f`` evaluated at ``p^{(k)}``. $_kw_others diff --git a/src/solvers/interior_point_Newton.jl b/src/solvers/interior_point_Newton.jl index 7d726e47a5..6357c01a9f 100644 --- a/src/solvers/interior_point_Newton.jl +++ b/src/solvers/interior_point_Newton.jl @@ -39,8 +39,8 @@ the constraints are further fulfilled. * `M`: a manifold ``$(_math(:M))`` * `f`: a cost function ``f : $(_math(:M)) → ℝ`` to minimize -* `grad_f`: the gradient ``$(_l_grad) f : $(_math(:M)) → T $(_math(:M))`` of ``f`` -* `Hess_f`: the Hessian ``$(_l_Hess)f(p): T_p$(_math(:M)) → T_p$(_math(:M))``, ``X ↦ $(_l_Hess)f(p)[X] = ∇_X$(_l_grad)f(p)`` +* `grad_f`: the gradient ``$(_tex(:grad)) f : $(_math(:M)) → T $(_math(:M))`` of ``f`` +* `Hess_f`: the Hessian ``$(_tex(:Hess))f(p): T_p$(_math(:M)) → T_p$(_math(:M))``, ``X ↦ $(_tex(:Hess))f(p)[X] = ∇_X$(_tex(:grad))f(p)`` $(_var(:Field, :p)) or a [`ConstrainedManifoldObjective`](@ref) `cmo` containing `f`, `grad_f`, `Hess_f`, and the constraints diff --git a/src/solvers/particle_swarm.jl b/src/solvers/particle_swarm.jl index 395167435c..e5bcb833c4 100644 --- a/src/solvers/particle_swarm.jl +++ b/src/solvers/particle_swarm.jl @@ -40,7 +40,7 @@ The `p` used in the following defaults is the type of one point from the swarm. * `inverse_retraction_method=default_inverse_retraction_method(M, eltype(swarm))`: an inverse retraction to use. * $(_kw_retraction_method_default) * `social_weight=1.4` -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(500)`$(_sc_any)[`StopWhenChangeLess`](@ref)`(1e-4)` +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(500)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-4)` * $(_kw_vector_transport_method_default) # See also @@ -223,8 +223,8 @@ $_doc_swarm_global_best # Input -$_arg_M -$_arg_f +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) * `swarm = [rand(M) for _ in 1:swarm_size]`: an initial swarm of points. Instead of a cost function `f` you can also provide an [`AbstractManifoldCostObjective`](@ref) `mco`. @@ -237,7 +237,7 @@ Instead of a cost function `f` you can also provide an [`AbstractManifoldCostObj * $(_kw_retraction_method_default): $(_kw_retraction_method) * `social_weight=1.4`: a social weight factor * `swarm_size=100`: swarm size, if it should be generated randomly -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(500)`$(_sc_any)[`StopWhenChangeLess`](@ref)`(1e-4)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(500)`$(_sc(:Any))[`StopWhenChangeLess`](@ref)`(1e-4)`: $(_kw_stopping_criterion) * $(_kw_vector_transport_method_default): $(_kw_vector_transport_method) * `velocity`: a set of tangent vectors (of type `AbstractVector{T}`) representing the velocities of the particles, per default a random tangent vector per initial position diff --git a/src/solvers/proximal_bundle_method.jl b/src/solvers/proximal_bundle_method.jl index 457c0377a2..aebd308de6 100644 --- a/src/solvers/proximal_bundle_method.jl +++ b/src/solvers/proximal_bundle_method.jl @@ -48,7 +48,7 @@ Generate the state for the [`proximal_bundle_method`](@ref) on the manifold `M` * $(_kw_inverse_retraction_method_default): $(_kw_inverse_retraction_method) * $(_kw_p_default): $(_kw_p) * $(_kw_retraction_method_default): $(_kw_retraction_method) -* `stopping_criterion=`[`StopWhenLagrangeMultiplierLess`](@ref)`(1e-8)`$(_sc_any)[`StopAfterIteration`](@ref)`(5000)` +* `stopping_criterion=`[`StopWhenLagrangeMultiplierLess`](@ref)`(1e-8)`$(_sc(:Any))[`StopAfterIteration`](@ref)`(5000)` * `sub_problem=`[`proximal_bundle_method_subsolver`](@ref) * `sub_state=`[`AllocatingEvaluation`](@ref) * $(_kw_vector_transport_method_default): $(_kw_vector_transport_method) @@ -219,8 +219,8 @@ _doc_PBM = """ proximal_bundle_method(M, f, ∂f, p, kwargs...) proximal_bundle_method!(M, f, ∂f, p, kwargs...) -perform a proximal bundle method ``p^{(k+1)} = $(_l_retr)_{p^{(k)}}(-d_k)``, -where ``$(_l_retr)`` is a retraction and +perform a proximal bundle method ``p^{(k+1)} = $(_tex(:retr))_{p^{(k)}}(-d_k)``, +where ``$(_tex(:retr))`` is a retraction and $(_doc_PBM_dk) @@ -231,10 +231,10 @@ For more details see [HoseiniMonjeziNobakhtianPouryayevali:2021](@cite). # Input -$(_arg_M) -$(_arg_f) +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $(_arg_subgrad_f) -$(_arg_p) +$(_var(:Argument, :p)) # Keyword arguments @@ -247,7 +247,7 @@ $(_arg_p) * `m=0.0125`: a real number that controls the decrease of the cost function * `μ=0.5`: initial proximal parameter for the subproblem * $(_kw_retraction_method_default): $(_kw_retraction_method) -* `stopping_criterion=`[`StopWhenLagrangeMultiplierLess`](@ref)`(1e-8)`$(_sc_any)[`StopAfterIteration`](@ref)`(5000)`: +* `stopping_criterion=`[`StopWhenLagrangeMultiplierLess`](@ref)`(1e-8)`$(_sc(:Any))[`StopAfterIteration`](@ref)`(5000)`: $(_kw_stopping_criterion) * `sub_problem=`[`proximal_bundle_method_subsolver`](@ref) * `sub_state=`[`AllocatingEvaluation`](@ref) diff --git a/src/solvers/quasi_Newton.jl b/src/solvers/quasi_Newton.jl index 2f5ea0f64f..61c2d38556 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 -* $(_field_p) +$(_var(:Field, :p)) * `p_old`: the last iterate * `sk`: the current step * `yk`: the current gradient difference @@ -30,7 +30,7 @@ Generate the Quasi Newton state on the manifold `M` with start point `p`. ## Keyword arguments * `direction_update=`[`QuasiNewtonLimitedMemoryDirectionUpdate`](@ref)`(M, p, InverseBFGS(), 20; vector_transport_method=vector_transport_method)` -* `stopping_criterion=`[`StopAfterIteration`9(@ref)`(1000)`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-6)` +* `stopping_criterion=`[`StopAfterIteration`9(@ref)`(1000)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-6)` * $(_kw_retraction_method_default): $(_kw_retraction_method) * `stepsize=default_stepsize(M; QuasiNewtonState)`: $(_kw_stepsize) The default here is the [`WolfePowellLinesearch`](@ref) using the keywords `retraction_method` and `vector_transport_method` @@ -186,18 +186,18 @@ $(_problem_default) with start point `p`. The iterations can be done in-place of `p```=p^{(0)}``. The ``k``th iteration consists of -1. Compute the search direction ``η^{(k)} = -$(_tex(:Cal, "B"))_k [$(_l_grad)f (p^{(k)})]`` or solve ``$(_tex(:Cal, "H"))_k [η^{(k)}] = -$(_l_grad)f (p^{(k)})]``. +1. Compute the search direction ``η^{(k)} = -$(_tex(:Cal, "B"))_k [$(_tex(:grad))f (p^{(k)})]`` or solve ``$(_tex(:Cal, "H"))_k [η^{(k)}] = -$(_tex(:grad))f (p^{(k)})]``. 2. Determine a suitable stepsize ``α_k`` along the curve ``γ(α) = R_{p^{(k)}}(α η^{(k)})``, usually by using [`WolfePowellLinesearch`](@ref). 3. Compute ``p^{(k+1)} = R_{p^{(k)}}(α_k η^{(k)})``. -4. Define ``s_k = $(_tex(:Cal, "T"))_{p^{(k)}, α_k η^{(k)}}(α_k η^{(k)})`` and ``y_k = $(_l_grad)f(p^{(k+1)}) - $(_tex(:Cal, "T"))_{p^{(k)}, α_k η^{(k)}}($(_l_grad)f(p^{(k)}))``, where ``$(_tex(:Cal, "T"))`` denotes a vector transport. +4. Define ``s_k = $(_tex(:Cal, "T"))_{p^{(k)}, α_k η^{(k)}}(α_k η^{(k)})`` and ``y_k = $(_tex(:grad))f(p^{(k+1)}) - $(_tex(:Cal, "T"))_{p^{(k)}, α_k η^{(k)}}($(_tex(:grad))f(p^{(k)}))``, where ``$(_tex(:Cal, "T"))`` denotes a vector transport. 5. Compute the new approximate Hessian ``H_{k+1}`` or its inverse ``B_{k+1}``. # Input -$(_arg_M) -$(_arg_f) +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $(_arg_grad_f) -$(_arg_p) +$(_var(:Argument, :p)) # Keyword arguments @@ -235,7 +235,7 @@ $(_arg_p) * $(_kw_retraction_method_default): $(_kw_retraction_method) * `stepsize=`[`WolfePowellLinesearch`](@ref)`(retraction_method, vector_transport_method)`: $(_kw_stepsize) -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(max(1000, memory_size))`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-6)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(max(1000, memory_size))`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-6)`: $(_kw_stopping_criterion) * $(_kw_vector_transport_method_default): $(_kw_vector_transport_method) diff --git a/src/solvers/stochastic_gradient_descent.jl b/src/solvers/stochastic_gradient_descent.jl index 4a1620ad59..e4332d0bf3 100644 --- a/src/solvers/stochastic_gradient_descent.jl +++ b/src/solvers/stochastic_gradient_descent.jl @@ -150,10 +150,10 @@ perform a stochastic gradient descent. This can be perfomed in-place of `p`. # Input -$(_arg_M) +$(_var(:Argument, :M; type=true)) * `grad_f`: a gradient function, that either returns a vector of the gradients or is a vector of gradient functions -$(_arg_p) +$(_var(:Argument, :p)) alternatively to the gradient you can provide an [`ManifoldStochasticGradientObjective`](@ref) `msgo`, then using the `cost=` keyword does not have any effect since if so, the cost is already within the objective. diff --git a/src/solvers/subgradient.jl b/src/solvers/subgradient.jl index e3c075f620..c1206e4acf 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 -* $(_field_p) +$(_var(:Field, :p)) * `p_star`: optimal value * $(_field_retr) * $(_field_step) @@ -91,8 +91,8 @@ _doc_SGM = """ subgradient_method!(M, f, ∂f, p; kwargs...) subgradient_method!(M, sgo, p; kwargs...) -perform a subgradient method ``p^{(k+1)} = $(_l_retr)\\bigl(p^{(k)}, s^{(k)}∂f(p^{(k)})\\bigr)``, -where ``$(_l_retr)`` is a retraction, ``s^{(k)}`` is a step size. +perform a subgradient method ``p^{(k+1)} = $(_tex(:retr))\\bigl(p^{(k)}, s^{(k)}∂f(p^{(k)})\\bigr)``, +where ``$(_tex(:retr))`` is a retraction, ``s^{(k)}`` is a step size. Though the subgradient might be set valued, the argument `∂f` should always return _one_ element from the subgradient, but @@ -101,10 +101,10 @@ For more details see [FerreiraOliveira:1998](@cite). # Input -$(_arg_M) -$(_arg_f) +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) * `∂f`: the (sub)gradient ``∂ f: $(_math(:M)) → T$(_math(:M))`` of f -$(_arg_p) +$(_var(:Argument, :p)) alternatively to `f` and `∂f` a [`ManifoldSubgradientObjective`](@ref) `sgo` can be provided. diff --git a/src/solvers/truncated_conjugate_gradient_descent.jl b/src/solvers/truncated_conjugate_gradient_descent.jl index 5721a63b25..cebc7ce501 100644 --- a/src/solvers/truncated_conjugate_gradient_descent.jl +++ b/src/solvers/truncated_conjugate_gradient_descent.jl @@ -18,7 +18,7 @@ Let `T` denote the type of a tangent vector and `R <: Real`. * $(_field_stop) * `θ::R`: the superlinear convergence target rate of ``1+θ`` * `trust_region_radius::R`: the trust-region radius -* `X::T`: the gradient ``$(_l_grad)f(p)`` +* `X::T`: the gradient ``$(_tex(:grad))f(p)`` * `Y::T`: current iterate tangent vector * `z::T`: the preconditioned residual * `z_r::R`: inner product of the residual and `z` @@ -42,8 +42,8 @@ Initialise the TCG state. * `θ=1.0` * `trust_region_radius=`[`injectivity_radius`](@extref `ManifoldsBase.injectivity_radius-Tuple{AbstractManifold}`)`(base_manifold(TpM)) / 4` * `stopping_criterion=`[`StopAfterIteration`](@ref)`(`$(_link(:manifold_dimension; M="base_manifold(Tpm)"))`)` - $(_sc_any)[`StopWhenResidualIsReducedByFactorOrPower`](@ref)`(; κ=κ, θ=θ)`$(_sc_any)[`StopWhenTrustRegionIsExceeded`](@ref)`()` - $(_sc_any)[`StopWhenCurvatureIsNegative`](@ref)`()`$(_sc_any)[`StopWhenModelIncreased`](@ref)`()`: + $(_sc(:Any))[`StopWhenResidualIsReducedByFactorOrPower`](@ref)`(; κ=κ, θ=θ)`$(_sc(:Any))[`StopWhenTrustRegionIsExceeded`](@ref)`()` + $(_sc(:Any))[`StopWhenCurvatureIsNegative`](@ref)`()`$(_sc(:Any))[`StopWhenModelIncreased`](@ref)`()`: $(_kw_stopping_criterion) # See also @@ -288,7 +288,7 @@ end StopWhenCurvatureIsNegative <: StoppingCriterion A functor for testing if the curvature of the model is negative, -``⟨δ_k, $(_l_Hess) F(p)[δ_k]⟩_p ≦ 0``. +``⟨δ_k, $(_tex(:Hess)) F(p)[δ_k]⟩_p ≦ 0``. In this case, the model is not strictly convex, and the stepsize as computed does not yield a reduction of the model. @@ -429,12 +429,12 @@ see [AbsilBakerGallivan:2006, ConnGouldToint:2000](@cite). # Input -$(_arg_M) -$(_arg_f) +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $(_arg_grad_f) $(_arg_Hess_f) -$(_arg_p) -$(_arg_X) +$(_var(:Argument, :p)) +$(_var(:Argument, :X)) Instead of the three functions, you either provide a [`ManifoldHessianObjective`](@ref) `mho` which is then used to build the trust region model, or a [`TrustRegionModelObjective`](@ref) `trmo` @@ -454,8 +454,8 @@ directly. This disables preconditioning. * $(_kw_retraction_method_default): $(_kw_retraction_method) * `stopping_criterion=`[`StopAfterIteration`](@ref)`(`$(_link(:manifold_dimension; M="base_manifold(Tpm)"))`)` - $(_sc_any)[`StopWhenResidualIsReducedByFactorOrPower`](@ref)`(; κ=κ, θ=θ)`$(_sc_any)[`StopWhenTrustRegionIsExceeded`](@ref)`()` - $(_sc_any)[`StopWhenCurvatureIsNegative`](@ref)`()`$(_sc_any)[`StopWhenModelIncreased`](@ref)`()`: + $(_sc(:Any))[`StopWhenResidualIsReducedByFactorOrPower`](@ref)`(; κ=κ, θ=θ)`$(_sc(:Any))[`StopWhenTrustRegionIsExceeded`](@ref)`()` + $(_sc(:Any))[`StopWhenCurvatureIsNegative`](@ref)`()`$(_sc(:Any))[`StopWhenModelIncreased`](@ref)`()`: $(_kw_stopping_criterion) * `trust_region_radius=`[`injectivity_radius`](@extref `ManifoldsBase.injectivity_radius-Tuple{AbstractManifold}`)`(M) / 4`: the initial trust-region radius diff --git a/src/solvers/trust_regions.jl b/src/solvers/trust_regions.jl index baba93c13b..85dcdf32cf 100644 --- a/src/solvers/trust_regions.jl +++ b/src/solvers/trust_regions.jl @@ -8,9 +8,9 @@ Store the state of the trust-regions solver. * `acceptance_rate`: a lower bound of the performance ratio for the iterate that decides if the iteration is accepted or not. -* `HX`, `HY`, `HZ`: interim storage (to avoid allocation) of ``$(_l_Hess) f(p)[⋅]` of `X`, `Y`, `Z` +* `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 -* $(_field_p) +$(_var(:Field, :p)) * `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) @@ -40,7 +40,7 @@ create a trust region state. # Input -$(_arg_M) +$(_var(:Argument, :M; type=true)) $_arg_sub_problem $_arg_sub_state @@ -50,7 +50,7 @@ $_arg_sub_state * `max_trust_region_radius=sqrt(manifold_dimension(M))` * $(_kw_p_default): $(_kw_p) * `project!=copyto!` -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(1000)`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-6)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(1000)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-6)`: $(_kw_stopping_criterion) * `randomize=false` * `ρ_regularization=10000.0` @@ -269,11 +269,11 @@ by default the [`truncated_conjugate_gradient_descent`](@ref) is used. # Input -$(_arg_M) -$(_arg_f) +$(_var(:Argument, :M; type=true)) +$(_var(:Argument, :f)) $(_arg_grad_f) $(_arg_Hess_f) -$(_arg_p) +$(_var(:Argument, :p)) # Keyword arguments @@ -299,7 +299,7 @@ $(_arg_p) * `reduction_threshold=0.1`: trust-region reduction threshold: if ρ is below this threshold, the trust region radius is reduced by `reduction_factor`. * $(_kw_retraction_method_default): $(_kw_retraction_method) -* `stopping_criterion=`[`StopAfterIteration`](@ref)`(1000)`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-6)`: +* `stopping_criterion=`[`StopAfterIteration`](@ref)`(1000)`$(_sc(:Any))[`StopWhenGradientNormLess`](@ref)`(1e-6)`: $(_kw_stopping_criterion) * $(_kw_sub_kwargs_default): $(_kw_sub_kwargs) * `sub_stopping_criterion` – the default from [`truncated_conjugate_gradient_descent`](@ref):