First base for a glossary.

ext/ManoptLRUCacheExt.jl

@@ -27,7 +27,7 @@ Given a vector of symbols `caches`, this function sets up the
 
 # Keyword arguments
 
-* `p=`$(Manopt._link_rand()): a point on a manifold, to both infer its type for keys and initialize caches
+* `p=`$(Manopt._link(:rand)): a point on a manifold, to both infer its type for keys and initialize caches
 * `value=0.0`:
    a value both typing and initialising number-caches, the default is for (Float) values like the cost.
 * `X=zero_vector(M, p)`:

src/Manopt.jl

@@ -149,6 +149,8 @@ using Requires
 using SparseArrays
 using Statistics
 
+include("documentation_glossary.jl")
+
 """
     Rn(args; kwargs...)
     Rn(s::Symbol=:Manifolds, args; kwargs...)

src/plans/documentation_glossary.jl → src/documentation_glossary.jl

@@ -28,6 +28,7 @@ if that entrs is
 * a function, it is called with `args...` and `kwargs...` passed
 * a dictionary, then the arguments and keyword arguments are passed to this dictionary, assuming `args[1]` is a symbol
 """
+#do not document for now, until we have an internals section
 glossary(s::Symbol, args...; kwargs...) = glossary(_manopt_glossary, s, args...; kwargs...)
 function glossary(g::_MANOPT_DOC_TYPE, s::Symbol, args...; kwargs...)
     return glossary(g[s], args...; kwargs...)
@@ -58,6 +59,9 @@ _tex(args...; kwargs...) = glossary(:LaTeX, args...; kwargs...)
 # Mathematics and semantic symbols
 # :symbol the symbol,
 # :descr the description
+define!(:Math, :M, _tex(:Cal, "M"))
+define!(:Math, :Manifold, :symbol, _tex(:Cal, "M"))
+define!(:Math, :Manifold, :descrption, "the Riemannian manifold")
 define!(
     :Math, :vector_transport, :symbol, (a="⋅", b="⋅") -> raw"\mathcal T_{" * "$a←$b" * "}"
 )
@@ -67,15 +71,26 @@ _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...)
+_link(args...; kwargs...) = glossary(:Link, args...; kwargs...)
 define!(:Link, :Manopt, "[`Manopt.jl`](https://manoptjl.org)")
 define!(
     :Link,
     :rand,
     (; M="M") ->
         "[`rand`](@extref Base.rand-Tuple{AbstractManifold})$(length(M) > 0 ? "`($M)`" : "")",
 )
-
+define!(
+    :Link,
+    :zero_vector,
+    (; M="M", p="p") ->
+        "[`zero_vector`](@extref `ManifoldsBase.zero_vector-Tuple{AbstractManifold, Any}`)$(length(M) > 0 ? "`($M, $p)`" : "")",
+)
+define!(
+    :Link,
+    :manifold_dimension,
+    (; M="M") ->
+        "[`manifold_dimension`](@extref `ManifoldsBase.manifold_dimension-Tuple{AbstractManifold}`)$(length(M) > 0 ? "`($M)`" : "")",
+)
 # ---
 # Variables
 # in fields, keyword arguments, parameters
@@ -113,39 +128,51 @@ define!(
 )
 define!(:Variable, :p, :type, "P")
 define!(:Variable, :p, :default, (; M="M") -> _link(:rand; M=M))
-#=  Old ones
-_var[:vector_transport_method] = Dict(
-    :description =>
-        (; M="M", p="p") ->
-            "a vector transport ``$(_math[:vector_transport][:symbol]())`` to use, see [the section on vector transports](@extref ManifoldsBase :doc:`vector_transports`)",
-    :type => "AbstractVectorTransportMethod",
-    :default =>
-        (; M="M", p="p") ->
-            "[`default_vector_transport_method`](@extref `ManifoldsBase.default_vector_transport_method-Tuple{AbstractManifold}`)`($M, typeof($p))`",
+
+define!(
+    :Variable,
+    :vector_transport_method,
+    :description,
+    (; M="M", p="p") ->
+        "a vector transport ``$(_math(:vector_transport, :symbol))`` to use, see [the section on vector transports](@extref ManifoldsBase :doc:`vector_transports`)",
+)
+define!(:Variable, :vector_transport_method, :type, "AbstractVectorTransportMethodP")
+define!(
+    :Variable,
+    :vector_transport_method,
+    :default,
+    (; M="M", p="p") ->
+        "[`default_vector_transport_method`](@extref `ManifoldsBase.default_vector_transport_method-Tuple{AbstractManifold}`)`($M, typeof($p))`",
 )
-_var[:X] = Dict(
-    :description =>
-        (; M="M", p="p") ->
-            "a tangent bector at the point `$p` on the manifold ``$(_l[:Cal]("M"))``",
-    :type => "T",
-    :default => (; M="M", p="p") -> "`zero_vector($M,$p)`", # TODO Fix when the Links dictionary exists
-) =#
-# ---
-# Problems
 
-# ---
-# Notes
-_manopt_glossary[:Note] = _MANOPT_DOC_TYPE()
-_note = _manopt_glossary[:Note]
-_note[:ManifoldDefaultFactory] =
-    (type::String,) -> """
+define!(
+    :Variable,
+    :X,
+    :description,
+    (; M="M", p="p") ->
+        "a tangent bector at the point ``$p`` on the manifold ``$(_tex(:Cal, M))``",
+)
+define!(:Variable, :X, :type, "X")
+define!(:Variable, :X, :default, (; M="M", p="p") -> _link(:zero_vector; M=M, p=p))
+
+#
+#
+# Notes / Remarks
+_note(args...; kwargs...) = glossary(:Note, args...; kwargs...)
+
+define!(
+    :Note,
+    :ManifoldDefaultFactory,
+    (type::String) -> """
 !!! info
     This function generates a [`ManifoldDefaultsFactory`](@ref) for [`$(type)`]()@ref).
     If you do not provide a manifold, the manifold `M` later provided to (usually) generate
     the corresponding [`AbstractManoptSolverState`](@ref) will be used.
     This affects all arguments and keyword argumentss with defaults that depend on the manifold,
     unless provided with a value here.
-"""
+""",
+)
+
 # ---
 # Old strings
 
@@ -165,7 +192,7 @@ _l_norm(v, i="") = raw"\lVert" * "$v" * raw"\rVert" * "_{$i}"
 _l_Manifold(M="M") = _tex(:Cal, "M")
 _l_M = "$(_l_Manifold())"
 _l_TpM(p="p") = "T_{$p}$_l_M"
-_l_DΛ = "DΛ: T_{m}$(_l_M) → T_{Λ(m)}$(_l_Manifold("N"))"
+_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}"
@@ -188,23 +215,6 @@ function _math_sequence(name, index, i_start=1, i_end="n")
     return "\\{$(name)_{$index}\\}_{i=$(i_start)}^{$i_end}"
 end
 
-#
-#
-# Links
-
-function _link_zero_vector(M="M", p="p")
-    arg = length(M) > 0 ? "`($M, $p)`" : ""
-    return "[`zero_vector`](@extref `ManifoldsBase.zero_vector-Tuple{AbstractManifold, Any}`)$arg"
-end
-function _link_manifold_dimension(M="M")
-    arg = length(M) > 0 ? "`($M)`" : ""
-    return "[`manifold_dimension`](@extref `ManifoldsBase.manifold_dimension-Tuple{AbstractManifold}`)$arg"
-end
-function _link_rand(M="M")
-    arg = length(M) > 0 ? "`($M)`" : ""
-    return "[`rand`](@extref Base.rand-Tuple{AbstractManifold})$arg"
-end
-
 #
 #
 # Problems
@@ -265,8 +275,8 @@ _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)} ∈ $(_l_M)``"
-_field_gradient = "`X`: the current gradient ``$(_l_grad)f(p^{(k)}) ∈ T_p$(_l_M)``"
+_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_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``"
@@ -293,7 +303,7 @@ All other keyword arguments are passed to [`decorate_state!`](@ref) for state de
 [`decorate_objective!`](@ref) for objective, respectively.
 """
 
-_kw_p_default = "`p=`$(_link_rand())"
+_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))`"
@@ -315,7 +325,7 @@ end
 _kw_vector_transport_method_default = "`vector_transport_method=`[`default_vector_transport_method`](@extref `ManifoldsBase.default_vector_transport_method-Tuple{AbstractManifold}`)`(M, typeof(p))`"
 _kw_vector_transport_method = "a vector transport ``$(_math(:vector_transport, :symbol))`` to use, see [the section on vector transports](@extref ManifoldsBase :doc:`vector_transports`)."
 
-_kw_X_default = "`X=`$(_link_zero_vector())"
+_kw_X_default = "`X=`$(_link(:zero_vector))"
 _kw_X = raw"specify a memory internally to store a tangent vector"
 _kw_X_init = raw"specify an initial value for the tangent vector"
 

src/helpers/checks.jl

@@ -82,7 +82,7 @@ Verify numerically whether the gradient `grad_f(M,p)` of `f(M,p)` is correct, th
 $_doc_check_gradient_formula
 
 or in other words, that the error between the function ``f`` and its first order Taylor
-behaves in error ``$_l[:Cal]("O") O(t^2)``, which indicates that the gradient is correct,
+behaves in error ``$(_tex(:Cal, "O"))(t^2)``, which indicates that the gradient is correct,
 cf. also [Boumal:2023; Section 4.8](@cite).
 
 Note that if the errors are below the given tolerance and the method is exact,
@@ -161,7 +161,7 @@ The approximation is then
 $_doc_check_Hess_formula
 
 or in other words, that the error between the function ``f`` and its second order Taylor
-behaves in error ``$_l[:Cal]("O") (t^3)``, which indicates that the Hessian is correct,
+behaves in error ``$(_tex(:Cal, "O"))(t^3)``, which indicates that the Hessian is correct,
 cf. also [Boumal:2023; Section 6.8](@cite).
 
 Note that if the errors are below the given tolerance and the method is exact,

src/plans/augmented_lagrangian_plan.jl

@@ -1,5 +1,5 @@
-#_doc_al_Cost() = "$(_l[:Cal]("L"))_\\rho(p, μ, λ)"
-_doc_al_Cost(iter) = "$(_l[:Cal]("L"))_{ρ^{($iter)}}(p, μ^{($iter)}, λ^{($iter)})"
+#_doc_al_Cost() = "$(_tex(:Cal, "L"))_\\rho(p, μ, λ)"
+_doc_al_Cost(iter) = "$(_tex(:Cal, "L"))_{ρ^{($iter)}}(p, μ^{($iter)}, λ^{($iter)})"
 _doc_AL_Cost_long = raw"""
 ```math
 \mathcal L_\rho(p, μ, λ)
@@ -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 $(_l[:Cal]("L"))_{ρ}(p, μ, λ)``, see also [`AugmentedLagrangianCost`](@ref).
+`$_l_grad $(_tex(:Cal, "L"))_{ρ}(p, μ, λ)``, see also [`AugmentedLagrangianCost`](@ref).
 
 ## Fields
 

src/plans/cache.jl

@@ -15,7 +15,7 @@ Both `X` and `c` are accompanied by booleans to keep track of their validity.
 
 ## Keyword arguments
 
-* `p=`$(_link_rand()): a point on the manifold to initialize the cache with
+* `p=`$(Manopt._link(:rand)): a point on the manifold to initialize the cache with
 * `X=get_gradient(M, obj, p)` or `zero_vector(M,p)`: a tangent vector to store the gradient in,
   see also `initialize=`
 * `c=[`get_cost`](@ref)`(M, obj, p)` or `0.0`: a value to store the cost function in `initialize`

src/plans/conjugate_residual_plan.jl

@@ -3,7 +3,7 @@
 # Objective.
 _doc_CR_cost = """
 ```math
-f(X) = $(_l[:frac](1,2)) $(_l_norm(_l[:Cal]("A")*"[X] + b","p"))^2,\\qquad X ∈ $(_l_TpM()),
+f(X) = $(_tex(:frac, 1,2)) $(_l_norm(_tex(:Cal, "A")*"[X] + b","p"))^2,\\qquad X ∈ $(_l_TpM()),
 ```
 """
 @doc """
@@ -13,9 +13,9 @@ Model the objective
 
 $(_doc_CR_cost)
 
-defined on the tangent space ``$(_l_TpM)`` at ``p`` on the manifold ``$(_l_M)``.
+defined on the tangent space ``$(_l_TpM)`` at ``p`` on the manifold ``$(_math(:M))``.
 
-In other words this is an objective to solve ``$(_l[:Cal]("A")) = -b(p)``
+In other words this is an objective to solve ``$(_tex(:Cal, "A")) = -b(p)``
 for some linear symmetric operator and a vector function.
 Note the minus on the right hand side, which makes this objective especially tailored
 for (iteratively) solving Newton-like equations.
@@ -84,7 +84,7 @@ end
 @doc """
     get_b(TpM::TangentSpace, slso::SymmetricLinearSystemObjective)
 
-evaluate the stored value for computing the right hand side ``b`` in ``$(_l[:Cal]("A"))=-b``.
+evaluate the stored value for computing the right hand side ``b`` in ``$(_tex(:Cal, "A"))=-b``.
 """
 function get_b(
     TpM::TangentSpace, slso::SymmetricLinearSystemObjective{AllocatingEvaluation}
@@ -106,7 +106,7 @@ evaluate the gradient of
 
 $(_doc_CR_cost)
 
-Which is ``$(_l_grad) f(X) = $(_l[:Cal]("A"))[X]+b``. This can be computed in-place of `Y`.
+Which is ``$(_l_grad) f(X) = $(_tex(:Cal, "A"))[X]+b``. This can be computed in-place of `Y`.
 """
 function get_gradient(TpM::TangentSpace, slso::SymmetricLinearSystemObjective, X)
     p = base_point(TpM)
@@ -141,7 +141,7 @@ evaluate the Hessian of
 
 $(_doc_CR_cost)
 
-Which is ``$(_l_Hess) f(X)[Y] = $(_l[:Cal]("A"))[V]``. This can be computed in-place of `W`.
+Which is ``$(_l_Hess) f(X)[Y] = $(_tex(:Cal, "A"))[V]``. This can be computed in-place of `W`.
 """
 function get_hessian(
     TpM::TangentSpace, slso::SymmetricLinearSystemObjective{AllocatingEvaluation}, X, V
@@ -179,10 +179,10 @@ A state for the [`conjugate_residual`](@ref) solver.
 # Fields
 
 * `X::T`: the iterate
-* `r::T`: the residual ``r = -b(p) - $(_l[:Cal]("A"))(p)[X]``
+* `r::T`: the residual ``r = -b(p) - $(_tex(:Cal, "A"))(p)[X]``
 * `d::T`: the conjugate direction
-* `Ar::T`, `Ad::T`: storages for ``$(_l[:Cal]("A"))(p)[d]``, ``$(_l[:Cal]("A"))(p)[r]``
-* `rAr::R`: internal field for storing ``⟨ r, $(_l[:Cal]("A"))(p)[r] ⟩``
+* `Ar::T`, `Ad::T`: storages for ``$(_tex(:Cal, "A"))(p)[d]``, ``$(_tex(:Cal, "A"))(p)[r]``
+* `rAr::R`: internal field for storing ``⟨ r, $(_tex(:Cal, "A"))(p)[r] ⟩``
 * `α::R`: a step length
 * `β::R`: the conjugate coefficient
 * `stop::TStop`: a [`StoppingCriterion`](@ref) for the solver
@@ -197,14 +197,14 @@ Initialise the state with default values.
 
 ## Keyword arguments
 
-* `X``$(_link_rand("TpM"))`
+* `X``$(_link(:zero_vector))`
 * `r=-get_gradient(TpM, slso, X)`
 * `d=copy(TpM, r)`
 * `Ar=get_hessian(TpM, slso, X, r)`
 * `Ad=copy(TpM, Ar)`
 * `α::R=0.0`
 * `β::R=0.0`
-* `stopping_criterion=`[`StopAfterIteration`](@ref)`($(_link_manifold_dimension()))`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-8)`
+* `stopping_criterion=`[`StopAfterIteration`](@ref)`($(_link(:manifold_dimension)))`$(_sc_any)[`StopWhenGradientNormLess`](@ref)`(1e-8)`
 
 # See also
 
@@ -292,10 +292,10 @@ Stop when re relative residual in the [`conjugate_residual`](@ref)
 is below a certain threshold, i.e.
 
 ```math
-$(_l_ds)$(_l[:frac](_l_norm("r^{(k)"),"c")) ≤ ε,
+$(_l_ds)$(_tex(:frac, _l_norm("r^{(k)"),"c")) ≤ ε,
 ```
 
-where ``c = $(_l_norm("b"))`` of the initial vector from the vector field in ``$(_l[:Cal]("A"))(p)[X] + b(p) = 0_p``,
+where ``c = $(_l_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