From 80c2aa045d4146231e4f9f2be5d9783077bc7b3d Mon Sep 17 00:00:00 2001 From: Ronny Bergmann Date: Tue, 20 Aug 2024 19:35:38 +0200 Subject: [PATCH] A bit of further glossary work. --- ext/ManoptManifoldsExt/ManoptManifoldsExt.jl | 6 +- ext/ManoptManifoldsExt/manifold_functions.jl | 2 +- src/documentation_glossary.jl | 69 +++++++++---------- src/plans/conjugate_residual_plan.jl | 8 +-- src/plans/higher_order_primal_dual_plan.jl | 16 ++--- src/plans/primal_dual_plan.jl | 8 +-- src/plans/proximal_plan.jl | 8 +-- src/plans/quasi_newton_plan.jl | 2 +- src/solvers/ChambollePock.jl | 16 ++--- src/solvers/NelderMead.jl | 4 +- src/solvers/augmented_Lagrangian_method.jl | 8 +-- src/solvers/conjugate_residual.jl | 2 +- .../difference-of-convex-proximal-point.jl | 4 +- src/solvers/difference_of_convex_algorithm.jl | 4 +- src/solvers/exact_penalty_method.jl | 2 +- src/solvers/interior_point_Newton.jl | 4 +- src/solvers/particle_swarm.jl | 2 +- src/solvers/primal_dual_semismooth_Newton.jl | 6 +- src/solvers/quasi_Newton.jl | 2 +- .../truncated_conjugate_gradient_descent.jl | 4 +- 20 files changed, 85 insertions(+), 92 deletions(-) diff --git a/ext/ManoptManifoldsExt/ManoptManifoldsExt.jl b/ext/ManoptManifoldsExt/ManoptManifoldsExt.jl index 1180ac6c37..f89cb3b46d 100644 --- a/ext/ManoptManifoldsExt/ManoptManifoldsExt.jl +++ b/ext/ManoptManifoldsExt/ManoptManifoldsExt.jl @@ -3,11 +3,7 @@ module ManoptManifoldsExt using ManifoldsBase: exp, log, ParallelTransport, vector_transport_to using Manopt using Manopt: - _tex, - _var, - _l_refl, - _kw_retraction_method_default, - _kw_inverse_retraction_method_default + _tex, _var, _kw_retraction_method_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 35397334cd..963ca32307 100644 --- a/ext/ManoptManifoldsExt/manifold_functions.jl +++ b/ext/ManoptManifoldsExt/manifold_functions.jl @@ -115,7 +115,7 @@ end Reflect the point `x` from the manifold `M` at point `p`, given by ```math -$_l_refl +$(_tex(:reflect)) ``` where ``$(_tex(:retr))`` and ``$(_tex(:invretr))`` denote a retraction and an inverse diff --git a/src/documentation_glossary.jl b/src/documentation_glossary.jl index 03a6eb8913..94e56a3085 100644 --- a/src/documentation_glossary.jl +++ b/src/documentation_glossary.jl @@ -58,14 +58,22 @@ 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, :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, :prox, raw"\operatorname{prox}") +define!(:LaTeX, :reflect, raw"\operatorname{refl}") +define!(:LaTeX, :retr, raw"\operatorname{retr}") +define!(:LaTeX, :subgrad, raw"∂") define!(:LaTeX, :text, (letter) -> raw"\text{" * "$letter" * "}") _tex(args...; kwargs...) = glossary(:LaTeX, args...; kwargs...) +# # --- # Mathematics and semantic symbols # :symbol the symbol, -# :descr the description +# :description the description define!(:Math, :M, _tex(:Cal, "M")) define!(:Math, :Manifold, :symbol, _tex(:Cal, "M")) define!(:Math, :Manifold, :descrption, "the Riemannian manifold") @@ -74,10 +82,10 @@ define!( ) define!(:Math, :vector_transport, :name, "the vector transport") _math(args...; kwargs...) = glossary(:Math, args...; kwargs...) +# # --- # Links # Collect short forms for links, especially Interdocs ones. -_manopt_glossary[:Link] = _MANOPT_DOC_TYPE() _link(args...; kwargs...) = glossary(:Link, args...; kwargs...) define!(:Link, :Manopt, "[`Manopt.jl`](https://manoptjl.org)") define!( @@ -199,6 +207,25 @@ define!( """, ) +define!( + :Problem, + :Constrained, + (; M="M", p="p") -> """ + ```math +\\begin{aligned} +\\min_{$p ∈ $(_tex(:Cal, M))} & f($p)\\\\ +$(_tex(:text, "subject to")) &g_i($p) ≤ 0 \\quad $(_tex(:text, " for ")) i= 1, …, m,\\\\ +\\quad & h_j($p)=0 \\quad $(_tex(:text, " for ")) j=1,…,n, +\\end{aligned} +``` +""", +) +define!( + :Problem, + :Default, + (; M="M", p="p") -> "\n```math\n$(_tex(:argmin))_{$p ∈ $(_tex(:Cal, M))} f($p)\n```\n", +) +_problem(args...; kwargs...) = glossary(:Problem, args...; kwargs...) # # # Stopping Criteria @@ -208,20 +235,9 @@ _sc(args...; kwargs...) = glossary(:StoppingCriterion, args...; kwargs...) # --- # Old strings - -# LateX symbols -_l_log = raw"\log" -_l_prox = raw"\operatorname{prox}" -_l_refl = raw"\operatorname{refl}_p(x) = \operatorname{retr}_p(-\operatorname{retr}^{-1}_p x)" -_l_subgrad = raw"∂" -_l_min = raw"\min" -_l_max = raw"\min" -_l_norm(v, i="") = raw"\lVert" * "$v" * raw"\rVert" * "_{$i}" # Semantics -_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_TpM(p="p") = "T_{$p}$(_tex(:Cal, "M"))" +_l_DΛ = "DΛ: T_{m}$(_math(:M)) → T_{Λ(m)}$(_tex(:Cal, "N")))" _l_C_subset_M = "$(_tex(:Cal, "C")) ⊂ $(_tex(:Cal, "M"))" # Math terms @@ -239,25 +255,6 @@ function _math_sequence(name, index, i_start=1, i_end="n") return "\\{$(name)_{$index}\\}_{i=$(i_start)}^{$i_end}" end -# -# -# Problems - -_problem_default = raw""" -```math -\operatorname*{arg\,min}_{p ∈ \mathcal M} f(p) -``` -""" - -_problem_constrained = raw"""```math -\begin{aligned} -\min_{p ∈\mathcal{M}} &f(p)\\ -\text{subject to } &g_i(p)\leq 0 \quad \text{ for } i= 1, …, m,\\ -\quad &h_j(p)=0 \quad \text{ for } j=1,…,n, -\end{aligned} -``` -""" - # Arguments of functions _arg_alt_mgo = raw""" Alternatively to `f` and `grad_f` you can provide @@ -294,7 +291,7 @@ To obtain the whole final state of the solver, see [`get_solver_return`](@ref) f _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 ``$(_l_subgrad)f(p^{(k)}) ∈ T_p$_l_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))``" _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" diff --git a/src/plans/conjugate_residual_plan.jl b/src/plans/conjugate_residual_plan.jl index 271509ac01..77d7fea4c5 100644 --- a/src/plans/conjugate_residual_plan.jl +++ b/src/plans/conjugate_residual_plan.jl @@ -3,7 +3,7 @@ # Objective. _doc_CR_cost = """ ```math -f(X) = $(_tex(:frac, 1,2)) $(_l_norm(_tex(:Cal, "A")*"[X] + b","p"))^2,\\qquad X ∈ $(_l_TpM()), +f(X) = $(_tex(:frac, 1,2)) $(_tex(:norm, _tex(:Cal, "A")*"[X] + b"; index="p"))^2,\\qquad X ∈ $(_l_TpM()), ``` """ @doc """ @@ -292,10 +292,10 @@ Stop when re relative residual in the [`conjugate_residual`](@ref) is below a certain threshold, i.e. ```math -$(_tex(:displaystyle))$(_tex(:frac, _l_norm("r^{(k)"),"c")) ≤ ε, +$(_tex(:displaystyle))$(_tex(:frac, _tex(:norm, "r^{(k)"),"c")) ≤ ε, ``` -where ``c = $(_l_norm("b"))`` of the initial vector from the vector field in ``$(_tex(:Cal, "A"))(p)[X] + b(p) = 0_p``, +where ``c = $(_tex(:norm, "b"))`` of the initial vector from the vector field in ``$(_tex(:Cal, "A"))(p)[X] + b(p) = 0_p``, from the [`conjugate_residual`](@ref) # Fields @@ -313,7 +313,7 @@ Initialise the stopping criterion. !!! note - The initial norm of the vector field ``c = $(_l_norm("b"))`` + The initial norm of the vector field ``c = $(_tex(:norm, "b"))`` that is stored internally is updated on initialisation, that is, if this stopping criterion is called with `k<=0`. """ diff --git a/src/plans/higher_order_primal_dual_plan.jl b/src/plans/higher_order_primal_dual_plan.jl index 4161684a9d..ec51dce7b8 100644 --- a/src/plans/higher_order_primal_dual_plan.jl +++ b/src/plans/higher_order_primal_dual_plan.jl @@ -68,10 +68,10 @@ end # Fields -* `m`: base point on ``$_l_M`` -* `n`: base point on ``$(_l_Manifold("N"))`` -* `x`: an initial point on ``x^{(0)} ∈ $_l_M`` (and its previous iterate) -* `ξ`: an initial tangent vector ``\\xi^{(0)} ∈ T_{n}^*$(_l_Manifold("N"))`` (and its previous iterate) +$(_var(:Field, :p, "m")) +$(_var(:Field, :p, "n"; M="N")) +$(_var(:Field, :p)) +$(_var(:Field, :X)) * `primal_stepsize::Float64`: proximal parameter of the primal prox * `dual_stepsize::Float64`: proximal parameter of the dual prox * `reg_param::Float64`: regularisation parameter for the Newton matrix @@ -202,14 +202,14 @@ function set_iterate!(pdsn::PrimalDualSemismoothNewtonState, p) pdsn.p = p return pdsn end -@doc raw""" +@doc """ y = get_differential_primal_prox(M::AbstractManifold, pdsno::PrimalDualManifoldSemismoothNewtonObjective σ, x) get_differential_primal_prox!(p::TwoManifoldProblem, y, σ, x) Evaluate the differential proximal map of ``F`` stored within [`AbstractPrimalDualManifoldObjective`](@ref) ```math -D\operatorname{prox}_{σF}(x)[X] +D$(_tex(:prox))_{σF}(x)[X] ``` which can also be computed in place of `y`. @@ -283,14 +283,14 @@ function get_differential_primal_prox!( return get_differential_primal_prox!(M, Y, get_objective(admo, false), σ, p, X) end -@doc raw""" +@doc """ η = get_differential_dual_prox(N::AbstractManifold, pdsno::PrimalDualManifoldSemismoothNewtonObjective, n, τ, X, ξ) get_differential_dual_prox!(N::AbstractManifold, pdsno::PrimalDualManifoldSemismoothNewtonObjective, η, n, τ, X, ξ) Evaluate the differential proximal map of ``G_n^*`` stored within [`PrimalDualManifoldSemismoothNewtonObjective`](@ref) ```math -D\operatorname{prox}_{τG_n^*}(X)[ξ] +D$(_tex(:prox))_{τG_n^*}(X)[ξ] ``` which can also be computed in place of `η`. diff --git a/src/plans/primal_dual_plan.jl b/src/plans/primal_dual_plan.jl index eec88ac43e..5d634a3247 100644 --- a/src/plans/primal_dual_plan.jl +++ b/src/plans/primal_dual_plan.jl @@ -96,14 +96,14 @@ function PrimalDualManifoldObjective( ) end -@doc raw""" +@doc """ q = get_primal_prox(M::AbstractManifold, p::AbstractPrimalDualManifoldObjective, σ, p) get_primal_prox!(M::AbstractManifold, p::AbstractPrimalDualManifoldObjective, q, σ, p) Evaluate the proximal map of ``F`` stored within [`AbstractPrimalDualManifoldObjective`](@ref) ```math -\operatorname{prox}_{σF}(x) +$(_tex(:prox))_{σF}(x) ``` which can also be computed in place of `y`. @@ -164,14 +164,14 @@ function get_primal_prox!( return get_primal_prox!(M, q, get_objective(admo, false), σ, p) end -@doc raw""" +@doc """ Y = get_dual_prox(N::AbstractManifold, apdmo::AbstractPrimalDualManifoldObjective, n, τ, X) get_dual_prox!(N::AbstractManifold, apdmo::AbstractPrimalDualManifoldObjective, Y, n, τ, X) Evaluate the proximal map of ``g_n^*`` stored within [`AbstractPrimalDualManifoldObjective`](@ref) ```math - Y = \operatorname{prox}_{τG_n^*}(X) + Y = $(_tex(:prox))}_{τG_n^*}(X) ``` which can also be computed in place of `Y`. diff --git a/src/plans/proximal_plan.jl b/src/plans/proximal_plan.jl index 4b852443c2..bf6a8ab2d3 100644 --- a/src/plans/proximal_plan.jl +++ b/src/plans/proximal_plan.jl @@ -3,16 +3,16 @@ # Proximal Point Problem and State # # -@doc raw""" +@doc """ ManifoldProximalMapObjective{E<:AbstractEvaluationType, TC, TP, V <: Vector{<:Integer}} <: AbstractManifoldCostObjective{E, TC} specify a problem for solvers based on the evaluation of proximal maps. # Fields -* `cost`: a function ``F:\mathcal M→ℝ`` to +* `cost`: a function ``F:$(_tex(:Cal, "M"))→ℝ`` to minimize -* `proxes`: proximal maps ``\operatorname{prox}_{λ\varphi}:\mathcal M→\mathcal M`` +* `proxes`: proximal maps ``$(_tex(:prox))_{λφ}:$(_tex(:Cal, "M")) → $(_tex(:Cal, "M"))`` as functions `(M, λ, p) -> q`. * `number_of_proxes`: number of proximal maps per function, to specify when one of the maps is a combined one such that the proximal maps @@ -154,7 +154,7 @@ Generate the options # Keyword arguments * `evaluation_order=:LinearOrder`: soecify the `order_type` -* `λ=i -> 1.0 / i` a function to compute the ``λ_k, k ∈ $(_l_Manifold("N"))``, +* `λ=i -> 1.0 / i` a function to compute the ``λ_k, k ∈ $(_tex(:Cal, "N"))``, * $(_kw_p_default): $(_kw_p) * `stopping_criterion=`[`StopAfterIteration`](@ref)`(2000)` diff --git a/src/plans/quasi_newton_plan.jl b/src/plans/quasi_newton_plan.jl index d42182ef00..9f1ca879f4 100644 --- a/src/plans/quasi_newton_plan.jl +++ b/src/plans/quasi_newton_plan.jl @@ -331,7 +331,7 @@ in both variants. The [`AbstractQuasiNewtonUpdateRule`](@ref) indicates which quasi-Newton update rule is used. In all of them, the Euclidean update formula is used to generate the matrix ``H_{k+1}`` and ``B_{k+1}``, and the basis ``$(_math_sequence("b", "i", "1", "n"))`` is transported into the upcoming tangent -space ``T_{p_{k+1}} $_l_M``, preferably with an isometric vector transport, or generated there. +space ``T_{p_{k+1}} $(_tex(:Cal, "M"))``, preferably with an isometric vector transport, or generated there. # Provided functors diff --git a/src/solvers/ChambollePock.jl b/src/solvers/ChambollePock.jl index 71ac1e8f5d..80b2425d22 100644 --- a/src/solvers/ChambollePock.jl +++ b/src/solvers/ChambollePock.jl @@ -9,9 +9,9 @@ stores all options and variables within a linearized or exact Chambolle Pock. * `dual_stepsize::R`: proximal parameter of the dual prox * $(_field_inv_retr) * `inverse_retraction_method_dual::`[`AbstractInverseRetractionMethod`](@extref `ManifoldsBase.AbstractInverseRetractionMethod`): - an inverse retraction ``$(_tex(:invretr))`` on ``$(_l_Manifold("N"))`` + an inverse retraction ``$(_tex(:invretr))`` on ``$(_tex(:Cal, "N"))`` * `m::P`: base point on ``$(_math(:M))`` -* `n::Q`: base point on ``$(_l_Manifold("N"))`` +* `n::Q`: base point on ``$(_tex(:Cal, "N"))`` * `p::P`: an initial point on ``p^{(0)} ∈ $(_math(:M))`` * `pbar::P`: the relaxed iterate used in the next dual update step (when using `:primal` relaxation) * `primal_stepsize::R`: proximal parameter of the primal prox @@ -26,9 +26,9 @@ stores all options and variables within a linearized or exact Chambolle Pock. * `update_dual_base`: function `(pr, st, k) -> n` to update the dual base * $(_field_vector_transp) * `vector_transport_method_dual::`[`AbstractVectorTransportMethod`](@extref `ManifoldsBase.AbstractVectorTransportMethod`): - a vector transport ``$(_math(:vector_transport, :symbol))``on ``$(_l_Manifold("N"))`` + a vector transport ``$(_math(:vector_transport, :symbol))``on ``$(_tex(:Cal, "N"))`` -Here, `P` is a point type on ``$(_math(:M))``, `T` its tangent vector type, `Q` a point type on ``$(_l_Manifold("N"))``, +Here, `P` is a point type on ``$(_math(:M))``, `T` its tangent vector type, `Q` a point type on ``$(_tex(:Cal, "N"))``, and `R<:Real` is a real number type where for the last two the functions a [`AbstractManoptProblem`](@ref)` p`, @@ -53,7 +53,7 @@ If you activate these to be different from the default identity, you have to pro * `primal_stepsize=1/sqrt(8)` * $_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 ``$(_l_Manifold("N"))``, see [the section on retractions and their inverses](@extref ManifoldsBase :doc:`retractions`). + an inverse retraction ``$(_tex(:invretr))`` to use on ``$(_tex(:Cal, "N"))``, see [the section on retractions and their inverses](@extref ManifoldsBase :doc:`retractions`). * `relaxation=1.0` * `relax=:primal`: relax the primal variable by default * $_kw_retraction_method_default: $_kw_retraction_method @@ -63,7 +63,7 @@ If you activate these to be different from the default identity, you have to pro * `update_dual_base=missing` * $_kw_vector_transport_method_default: $_kw_vector_transport_method * `vector_transport_method=`[`default_vector_transport_method`](@extref `ManifoldsBase.default_vector_transport_method-Tuple{AbstractManifold}`)`(N, typeof(n))`: - a vector transport ``$(_math(:vector_transport, :symbol))`` to use on ``$(_l_Manifold("N"))``, see [the section on vector transports](@extref ManifoldsBase :doc:`vector_transports`). + a vector transport ``$(_math(:vector_transport, :symbol))`` to use on ``$(_tex(:Cal, "N"))``, see [the section on vector transports](@extref ManifoldsBase :doc:`vector_transports`). if `Manifolds.jl` is loaded, `N` is also a keyword argument and set to `TangentBundle(M)` by default. """ @@ -239,7 +239,7 @@ For more details on the algorithm, see [BergmannHerzogSilvaLouzeiroTenbrinckVida * $_kw_evaluation_default: $_kw_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 $(_l_Manifold("N")), see [the section on retractions and their inverses](@extref ManifoldsBase :doc:`retractions`). + an inverse retraction ``$(_tex(:invretr))`` to use on $(_tex(:Cal, "N")), see [the section on retractions and their inverses](@extref ManifoldsBase :doc:`retractions`). * `Λ=missing`: the (forward) operator ``Λ(⋅)`` (required for the `:exact` variant) * `linearized_forward_operator=missing`: its linearization ``DΛ(⋅)[⋅]`` (required for the `:linearized` variant) * `primal_stepsize=1/sqrt(8)`: proximal parameter of the dual prox @@ -253,7 +253,7 @@ For more details on the algorithm, see [BergmannHerzogSilvaLouzeiroTenbrinckVida * $_kw_retraction_method_default: $_kw_retraction_method * $_kw_vector_transport_method_default: $_kw_vector_transport_method * `vector_transport_method_dual=`[`default_vector_transport_method`](@extref `ManifoldsBase.default_vector_transport_method-Tuple{AbstractManifold}`)`(N, typeof(n))`: - a vector transport ``$(_math(:vector_transport, :symbol))`` to use on $(_l_Manifold("N")), see [the section on vector transports](@extref ManifoldsBase :doc:`vector_transports`). + a vector transport ``$(_math(:vector_transport, :symbol))`` to use on $(_tex(:Cal, "N")), see [the section on vector transports](@extref ManifoldsBase :doc:`vector_transports`). $_doc_sec_output """ diff --git a/src/solvers/NelderMead.jl b/src/solvers/NelderMead.jl index 590f99cfef..d0f4e861df 100644 --- a/src/solvers/NelderMead.jl +++ b/src/solvers/NelderMead.jl @@ -184,11 +184,11 @@ _doc_NelderMead = """ NelderMead!(M::AbstractManifold, f, population) NelderMead!(M::AbstractManifold, mco::AbstractManifoldCostObjective, population) -Solve a Nelder-Mead minimization problem for the cost function ``f: $_l_M`` on the +Solve a Nelder-Mead minimization problem for the cost function ``f: $(_tex(:Cal, "M")) → ℝ`` on the manifold `M`. If the initial [`NelderMeadSimplex`](@ref) is not provided, a random set of 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``. +The algorithm consists of the following steps. Let ``d`` denote the dimension of the manifold ``$(_tex(:Cal, "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_{$(_tex(:text, "m"))}`` diff --git a/src/solvers/augmented_Lagrangian_method.jl b/src/solvers/augmented_Lagrangian_method.jl index 4f52e5e862..9a7bbe3cf8 100644 --- a/src/solvers/augmented_Lagrangian_method.jl +++ b/src/solvers/augmented_Lagrangian_method.jl @@ -231,12 +231,12 @@ This method can work in-place of `p`. The aim of the ALM is to find the solution of the constrained optimisation task -$_problem_constrained +$_problem(:Constrained) where `M` is a Riemannian manifold, and ``f``, ``$(_math_sequence("g", "i", "1", "n"))`` and ``$(_math_sequence("h", "j", "1", "m")) are twice continuously differentiable functions from `M` to ℝ. In every step ``k`` of the algorithm, the [`AugmentedLagrangianCost`](@ref) - ``$(_doc_al_Cost("k"))`` is minimized on $_l_M, + ``$(_doc_al_Cost("k"))`` is minimized on $(_tex(:Cal, "M")), where ``μ^{(k)} ∈ ℝ^n`` and ``λ^{(k)} ∈ ℝ^m`` are the current iterates of the Lagrange multipliers and ``ρ^{(k)}`` is the current penalty parameter. The Lagrange multipliers are then updated by @@ -247,13 +247,13 @@ and $_doc_alm_μ_update - where ``λ_{$_l_min} ≤ λ_{$_l_max}`` and ``μ_{$_l_max}`` are the multiplier boundaries. + where ``λ_{$(_tex(:text, "min"))} ≤ λ_{$(_tex(:text, "max"))}`` and ``μ_{$(_tex(:text, "max"))}`` are the multiplier boundaries. Next, the accuracy tolerance ``ϵ`` is updated as $_doc_alm_ε_update - where ``ϵ_{$_l_min}`` is the lowest value ``ϵ`` is allowed to become and ``θ_ϵ ∈ (0,1)`` is constant scaling factor. + where ``ϵ_{$(_tex(:text, "min"))}`` is the lowest value ``ϵ`` is allowed to become and ``θ_ϵ ∈ (0,1)`` is constant scaling factor. Last, the penalty parameter ``ρ`` is updated as follows: with diff --git a/src/solvers/conjugate_residual.jl b/src/solvers/conjugate_residual.jl index 6290133064..fa7c83bed9 100644 --- a/src/solvers/conjugate_residual.jl +++ b/src/solvers/conjugate_residual.jl @@ -41,7 +41,7 @@ Note that the right hand side of Step 7 is the same as evaluating ``$(_tex(:Cal, * `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)`, - where `c` is the norm of ``$(_l_norm("b"))``. + where `c` is the norm of ``$(_tex(:norm,"b"))``. # Output diff --git a/src/solvers/difference-of-convex-proximal-point.jl b/src/solvers/difference-of-convex-proximal-point.jl index 8d6f95bf1b..1bd50119b6 100644 --- a/src/solvers/difference-of-convex-proximal-point.jl +++ b/src/solvers/difference-of-convex-proximal-point.jl @@ -165,7 +165,7 @@ Compute the difference of convex proximal point algorithm [SouzaOliveira:2015](@ ``` where you have to provide the subgradient ``∂h`` of ``h`` and either -* the proximal map ``$(_l_prox)_{λg}`` of `g` as a function `prox_g(M, λ, p)` or `prox_g(M, q, λ, p)` +* the proximal map ``$(_tex(:prox))_{λg}`` of `g` as a function `prox_g(M, λ, p)` or `prox_g(M, q, λ, p)` * the functions `g` and `grad_g` to compute the proximal map using a sub solver * your own sub-solver, specified by `sub_problem=`and `sub_state=` @@ -174,7 +174,7 @@ Then repeat for ``k=0,1,…`` 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)})`` +3. ``r^{(k)} = $(_tex(:prox))_{λ_kg}(q^{(k)})`` 4. ``X^{(k)} = $(_tex(:invretr))_{p^{(k)}}(r^{(k)})`` 5. Compute a stepsize ``s_k`` and 6. set ``p^{(k+1)} = $(_tex(:retr))_{p^{(k)}}(s_kX^{(k)})``. diff --git a/src/solvers/difference_of_convex_algorithm.jl b/src/solvers/difference_of_convex_algorithm.jl index 091d89c2df..04161a534d 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 - $(_tex(:argmin))_{q∈$(_math(:M))}\\ g(p) - ⟨X, $(_l_log)_p q⟩ + $(_tex(:argmin))_{q∈$(_math(:M))}\\ g(p) - ⟨X, $(_tex(:log))_p q⟩ ``` is needed. Besides a problem and a state, one can also provide a function and @@ -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)} ∈ $(_tex(: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)}, $(_tex(:log))_{p^{(k)}}q⟩ ``` until the stopping criterion (see the `stopping_criterion` keyword is fulfilled. diff --git a/src/solvers/exact_penalty_method.jl b/src/solvers/exact_penalty_method.jl index 3ecc038366..e6bb3f5f78 100644 --- a/src/solvers/exact_penalty_method.jl +++ b/src/solvers/exact_penalty_method.jl @@ -188,7 +188,7 @@ _doc_EPM = """ perform the exact penalty method (EPM) [LiuBoumal:2019](@cite) The aim of the EPM is to find a solution of the constrained optimisation task -$(_problem_constrained) +$(_problem(:Constrained)) where `M` is a Riemannian manifold, and ``f``, ``$(_math_sequence("g", "i", "1", "n"))`` and ``$(_math_sequence("h", "j", "1", "m"))`` are twice continuously differentiable functions from `M` to ℝ. diff --git a/src/solvers/interior_point_Newton.jl b/src/solvers/interior_point_Newton.jl index 6357c01a9f..ddd321554d 100644 --- a/src/solvers/interior_point_Newton.jl +++ b/src/solvers/interior_point_Newton.jl @@ -14,7 +14,7 @@ perform the interior point Newton method following [LaiYoshise:2024](@cite). In order to solve the constrained problem -$_problem_constrained +$(_problem(:Constrained)) This algorithms iteratively solves the linear system based on extending the KKT system by a slack variable `s`. @@ -85,7 +85,7 @@ pass a [`ConstrainedManifoldObjective`](@ref) `cmo` * `sub_objective`: The [`SymmetricLinearSystemObjective`](@ref) modelling the system of equations to use in the sub solver, includes the [`CondensedKKTVectorFieldJacobian`](@ref) ``$(_tex(:Cal, "A"))(X)`` and the [`CondensedKKTVectorField`](@ref) ``b`` in ``$(_tex(:Cal, "A"))(X) + b = 0`` we aim to solve. $(_kw_used_in("sub_problem")) -* `sub_stopping_criterion=`[`StopAfterIteration`](@ref)`(manifold_dimension(M))`[` | `](@ref StopWhenAny)[`StopWhenRelativeResidualLess`](@ref)`(c,1e-8)`, where ``c = $(_l_norm("b"))`` from the system to solve. +* `sub_stopping_criterion=`[`StopAfterIteration`](@ref)`(manifold_dimension(M))`[` | `](@ref StopWhenAny)[`StopWhenRelativeResidualLess`](@ref)`(c,1e-8)`, where ``c = $(_tex(:norm,"b"))`` from the system to solve. $(_kw_used_in("sub_state")) * `sub_problem`: combining the `sub_objective` and the tangent space at ``(p,λ)``` on the manifold ``$(_math(:M)) × ℝ^n`` to a manopt problem. This is the manifold and objective for the sub solver. diff --git a/src/solvers/particle_swarm.jl b/src/solvers/particle_swarm.jl index e5bcb833c4..05008b71da 100644 --- a/src/solvers/particle_swarm.jl +++ b/src/solvers/particle_swarm.jl @@ -191,7 +191,7 @@ _doc_PSO = """ perform the particle swarm optimization algorithm (PSO) to solve -$(_problem_default) +$(_problem(:Default)) PSO starts with an initial `swarm` [BorckmansIshtevaAbsil:2010](@cite) of points on the manifold. diff --git a/src/solvers/primal_dual_semismooth_Newton.jl b/src/solvers/primal_dual_semismooth_Newton.jl index aca5d28562..94cf412173 100644 --- a/src/solvers/primal_dual_semismooth_Newton.jl +++ b/src/solvers/primal_dual_semismooth_Newton.jl @@ -14,10 +14,10 @@ Perform the Primal-Dual Riemannian semismooth Newton algorithm. $(_doc_PDSN_formula) -* `p, X`: primal and dual start points ``p∈$(_math(:M))`` and ``X ∈ T_n$(_l_Manifold("N"))`` -* `m,n`: base points on ``$(_math(:M))`` and ``$(_l_Manifold("N"))`, respectively. +* `p, X`: primal and dual start points ``p∈$(_math(:M))`` and ``X ∈ T_n$(_tex(:Cal, "N"))`` +* `m,n`: base points on ``$(_math(:M))`` and ``$(_tex(:Cal, "N"))`, respectively. * `linearized_forward_operator`: the linearization ``DΛ(⋅)[⋅]`` of the operator ``Λ(⋅)``. -* `adjoint_linearized_operator`: the adjoint ``DΛ^*`` of the linearized operator ``DΛ(m): $(_l_TpM("m")) → T_{Λ(m)}$(_l_Manifold("N"))`` +* `adjoint_linearized_operator`: the adjoint ``DΛ^*`` of the linearized operator ``DΛ(m): $(_l_TpM("m")) → T_{Λ(m)}$(_tex(:Cal, "N"))`` * `prox_F, prox_G_Dual`: the proximal maps of ``F`` and ``G^\\ast_n`` * `diff_prox_F, diff_prox_dual_G`: the (Clarke Generalized) differentials of the proximal maps of ``F`` and ``G^\\ast_n`` diff --git a/src/solvers/quasi_Newton.jl b/src/solvers/quasi_Newton.jl index 61c2d38556..c1cb7193a8 100644 --- a/src/solvers/quasi_Newton.jl +++ b/src/solvers/quasi_Newton.jl @@ -181,7 +181,7 @@ _doc_QN = """ Perform a quasi Newton iteration to solve -$(_problem_default) +$(_problem(:Default)) with start point `p`. The iterations can be done in-place of `p```=p^{(0)}``. The ``k``th iteration consists of diff --git a/src/solvers/truncated_conjugate_gradient_descent.jl b/src/solvers/truncated_conjugate_gradient_descent.jl index cebc7ce501..0f95254edf 100644 --- a/src/solvers/truncated_conjugate_gradient_descent.jl +++ b/src/solvers/truncated_conjugate_gradient_descent.jl @@ -138,7 +138,7 @@ A functor for testing if the norm of residual at the current iterate is reduced either by a power of 1+θ or by a factor κ compared to the norm of the initial residual. The criterion hence reads -``$(_l_norm("r_k","p")) ≦ $(_l_norm("r_0","p^{(0)}")) \\min \\bigl( κ, $(_l_norm("r_0","p^{(0)}")) \\bigr)``. +``$(_tex(:norm, "r_k"; index="p")) ≦ $(_tex(:norm, "r_0"; index="p^{(0)}")) $(_tex(:min)) $(_tex(:bigl))( κ, $(_tex(:norm, "r_0"; index="p^{(0)}")) $(_tex(:bigr)))``. # Fields @@ -228,7 +228,7 @@ end StopWhenTrustRegionIsExceeded <: StoppingCriterion A functor for testing if the norm of the next iterate in the Steihaug-Toint truncated conjugate gradient -method is larger than the trust-region radius ``θ ≤ $(_l_norm("Y^{(k)}^{*}","p^{(k)}"))`` +method is larger than the trust-region radius ``θ ≤ $(_tex(:norm, "Y^{(k)}^{*}"; index="p^{(k)}"))`` and to end the algorithm when the trust region has been left. # Fields