diff --git a/src/documentation_glossary.jl b/src/documentation_glossary.jl index d7ea13fa50..162d87f013 100644 --- a/src/documentation_glossary.jl +++ b/src/documentation_glossary.jl @@ -151,14 +151,14 @@ _var(args...; kwargs...) = glossary(:Variable, args...; kwargs...) define!( :Variable, :Argument, - (s::Symbol, display="$s", t=_var(s, :type); type=false, kwargs...) -> - "* `$(display)$(type ? "::$(t)" : "")`: $(_var(s, :description;kwargs...))", + (s::Symbol, display="$s", t=""; type=false, kwargs...) -> + "* `$(display)$(type ? "::$(length(t) > 0 ? t : _var(s, :type))" : "")`: $(_var(s, :description;kwargs...))", ) define!( :Variable, :Field, - (s::Symbol, display="$s", t=_var(s, :type); kwargs...) -> - "* `$(display)::$(t)`: $(_var(s, :description; kwargs...))", + (s::Symbol, display="$s", t=""; kwargs...) -> + "* `$(display)::$(length(t) > 0 ? t : _var(s, :type))`: $(_var(s, :description; kwargs...))", ) define!( :Variable, @@ -166,12 +166,13 @@ define!( ( s::Symbol, display="$s", - t=_var(s, :type); + t=""; + default="", type=false, description::Bool=true, kwargs..., ) -> - "* `$(display)$(type ? "::$(t)" : "")=`$(_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...))" : "")", ) # # Actual variables @@ -183,7 +184,6 @@ define!( (; M="M", p="p") -> "a cost function ``f: $(_tex(:Cal, M))→ ℝ`` implemented as `($M, $p) -> v`", ) -define!(:Variable, :f, :type, "Function") define!( :Variable, @@ -192,7 +192,6 @@ define!( (; M="M", p="p") -> "the (Riemannian) gradient ``$(_tex(:grad))f``: $(_math(:M, M=M)) → $(_math(:TpM; M=M, p=p)) of f as a function `(M, p) -> X` or a function `(M, X, p) -> X` computing `X` in-place", ) -define!(:Variable, :grad_f, :type, "Function") define!( :Variable, @@ -201,7 +200,6 @@ define!( (; M="M", p="p") -> "the (Riemannian) Hessian ``$(_tex(:Hess))f``: $(_math(:TpM, M=M, p=p)) → $(_math(:TpM; M=M, p=p)) of f as a function `(M, p, X) -> Y` or a function `(M, Y, p, X) -> Y` computing `Y` in-place", ) -define!(:Variable, :Hess_f, :type, "Function") define!( :Variable, :M, :description, (; M="M") -> "a Riemannian manifold ``$(_tex(:Cal, M))``" @@ -214,6 +212,60 @@ define!( define!(:Variable, :p, :type, "P") define!(:Variable, :p, :default, (; M="M") -> _link(:rand; M=M)) +define!( + :Variable, + :stopping_criterion, + :description, + (; M="M") -> "a functor indicating that the stopping criterion is fulfilled.", +) +define!(:Variable, :stopping_criterion, :type, "StoppingCriterion") + +define!( + :Variable, + :sub_problem, + :description, + (; M="M") -> + " specify a problem for a solver or a closed form solution function, which can be allocating or in-place.", +) +define!(:Variable, :sub_problem, :type, "Union{AbstractManoptProblem, F}") + +define!( + :Variable, + :sub_problem, + :description, + (; M="M") -> + " specify a problem for a solver or a closed form solution function, which can be allocating or in-place.", +) +define!(:Variable, :sub_problem, :type, "Union{AbstractManoptProblem, F}") + +define!( + :Variable, + :sub_state, + :description, + (; M="M") -> + " a state to specify the sub solver to use. For a closed form solution, this indicates the type of function.", +) +define!(:Variable, :sub_state, :type, "Union{AbstractManoptProblem, F}") + +define!(:Variable, :subgrad_f, :symbol, "∂f") +define!( + :Variable, + :subgrad_f, + :description, + (; M="M", p="p") -> """ +the subgradient ``∂f: $(_math(:M; M=M)) → $(_math(:TM; M=M))`` of f as a function `(M, p) -> X` +or a function `(M, X, p) -> X` computing `X` in-place. +This function should always only return one element from the subgradient. +""", +) +define!( + :Variable, + :subgrad_f, + :description, + (; M="M") -> + " a state to specify the sub solver to use. For a closed form solution, this indicates the type of function.", +) + define!( :Variable, :vector_transport_method, @@ -234,8 +286,8 @@ define!( :Variable, :X, :description, - (; M="M", p="p") -> - "a tangent bector at the point ``$p`` on the manifold ``$(_tex(:Cal, M))``", + (; M="M", p="p", note="") -> + "a tangent bector at the point ``$p`` on the manifold ``$(_tex(:Cal, M))``. $note", ) define!(:Variable, :X, :type, "X") define!(:Variable, :X, :default, (; M="M", p="p") -> _link(:zero_vector; M=M, p=p)) @@ -313,15 +365,6 @@ _sc(args...; kwargs...) = glossary(:StoppingCriterion, args...; kwargs...) # --- # Old strings -# Arguments -_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""" -* `∂f`: the subgradient ``∂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. - This function should always only return one element from the subgradient. -""" - # 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))``" diff --git a/src/plans/higher_order_primal_dual_plan.jl b/src/plans/higher_order_primal_dual_plan.jl index 0f6d430a07..ce42c612f2 100644 --- a/src/plans/higher_order_primal_dual_plan.jl +++ b/src/plans/higher_order_primal_dual_plan.jl @@ -108,8 +108,7 @@ Generate a state for the [`primal_dual_semismooth_Newton`](@ref). $_kw_retraction_method * $_kw_inverse_retraction_method_default: $_kw_inverse_retraction_method -* `stopping_criterion=`[`StopAfterIteration`](@ref)(50): - $_kw_stopping_criterion +* $(_var(:Keyword, :stopping_criterion; default="`[`StopAfterIteration`](@ref)`(50)`")) * $_kw_vector_transport_method_default: $_kw_vector_transport_method diff --git a/src/plans/interior_point_Newton_plan.jl b/src/plans/interior_point_Newton_plan.jl index 20b49167eb..e5b943d6c8 100644 --- a/src/plans/interior_point_Newton_plan.jl +++ b/src/plans/interior_point_Newton_plan.jl @@ -68,8 +68,8 @@ are used to fill in reasonable defaults for the keywords. $(_var(:Argument, :M; type=true)) * `cmo`: a [`ConstrainedManifoldObjective`](@ref) -$(_arg_sub_problem) -$(_arg_sub_state) +$(_var(:Argument, :sub_problem)) +$(_var(:Argument, :sub_state)) # Keyword arguments diff --git a/src/solvers/FrankWolfe.jl b/src/solvers/FrankWolfe.jl index 504713de64..b94105243f 100644 --- a/src/solvers/FrankWolfe.jl +++ b/src/solvers/FrankWolfe.jl @@ -40,8 +40,8 @@ Initialise the Frank Wolfe method state, where `sub_problem` is a closed form so ## Input $(_var(:Argument, :M; type=true)) -$_arg_sub_problem -$_arg_sub_state +$(_var(:Argument, :sub_problem)) +$(_var(:Argument, :sub_state)) ## Keyword arguments diff --git a/src/solvers/augmented_Lagrangian_method.jl b/src/solvers/augmented_Lagrangian_method.jl index 7cff293abb..518f4afc3e 100644 --- a/src/solvers/augmented_Lagrangian_method.jl +++ b/src/solvers/augmented_Lagrangian_method.jl @@ -329,7 +329,7 @@ Otherwise the problem is not constrained and a better solver would be for exampl * `sub_state=`[`QuasiNewtonState`](@ref)) using [`QuasiNewtonLimitedMemoryDirectionUpdate`](@ref) with [`InverseBFGS`](@ref) and `sub_stopping_criterion` as a stopping criterion. See also `sub_kwargs=`. -* `stopping_criterion=$_sc_alm_default`: $_kw_stopping_criterion +$(_var(:Keyword, :stopping_criterion; default= _sc_alm_default)) 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/convex_bundle_method.jl b/src/solvers/convex_bundle_method.jl index df3a79deb0..e1ff721579 100644 --- a/src/solvers/convex_bundle_method.jl +++ b/src/solvers/convex_bundle_method.jl @@ -43,8 +43,8 @@ Generate the state for the [`convex_bundle_method`](@ref) on the manifold `M` ## Input $(_var(:Argument, :M; type=true)) -$_arg_sub_problem -$_arg_sub_state +$(_var(:Argument, :sub_problem)) +$(_var(:Argument, :sub_state)) # Keyword arguments @@ -299,7 +299,7 @@ For more details, see [BergmannHerzogJasa:2024](@cite). $(_var(:Argument, :M; type=true)) $(_var(:Argument, :f)) -$(_arg_subgrad_f) +$(_var(:Argument, :subgrad_f, _var(:subgrad_f, :symbol))) $(_var(:Argument, :p)) # Keyword arguments diff --git a/src/solvers/difference-of-convex-proximal-point.jl b/src/solvers/difference-of-convex-proximal-point.jl index c1d14a7e84..96b434c2fc 100644 --- a/src/solvers/difference-of-convex-proximal-point.jl +++ b/src/solvers/difference-of-convex-proximal-point.jl @@ -34,8 +34,8 @@ construct an difference of convex proximal point state, where `sub_problem` is a ## Input $(_var(:Argument, :M; type=true)) -$_arg_sub_problem -$_arg_sub_state +$(_var(:Argument, :sub_problem)) +$(_var(:Argument, :sub_state)) # Keyword arguments diff --git a/src/solvers/proximal_bundle_method.jl b/src/solvers/proximal_bundle_method.jl index bb404b6198..fe2e691856 100644 --- a/src/solvers/proximal_bundle_method.jl +++ b/src/solvers/proximal_bundle_method.jl @@ -233,7 +233,7 @@ For more details see [HoseiniMonjeziNobakhtianPouryayevali:2021](@cite). $(_var(:Argument, :M; type=true)) $(_var(:Argument, :f)) -$(_arg_subgrad_f) +$(_var(:Argument, :subgrad_f, _var(:subgrad_f, :symbol))) $(_var(:Argument, :p)) # Keyword arguments diff --git a/src/solvers/trust_regions.jl b/src/solvers/trust_regions.jl index 4022c46606..c6954857a3 100644 --- a/src/solvers/trust_regions.jl +++ b/src/solvers/trust_regions.jl @@ -41,8 +41,8 @@ create a trust region state. # Input $(_var(:Argument, :M; type=true)) -$_arg_sub_problem -$_arg_sub_state +$(_var(:Argument, :sub_problem)) +$(_var(:Argument, :sub_state)) ## Keyword arguments