GitHub

Manopt.jl Developer guide

This section of the documentation provides an overview of the design concepts behind Manopt.jl and an introduction to its main data types and their relation.

The goal is to provide a detailed description for developers of aspects within Manopt.jl and to convey the design decisions behind the overall structure of Manopt.jl.

There are two main ingredients of Manopt.jl: The problem and the solver state. The problem represents the task to be solved, which by default includes the manifold an objective is defined on and the objective to solve. The solver's state represents all variables and parameters a solver requires for setup as well as during the iterations.

Pretty printing on REPL

On the Julia REPL Manopt.jl aims to provide detailed information about a solver run when the user activates such a feedback, i.e. when setting return_state = true such that a high level interface returns the whole solver state instead of (just) the final iterate reached.

Manopt.status_summary — Method
status_summary(io, e; context::Symbol = :default)
status_summary(e; context::Symbol = :default)

Return a string reporting about the current status of an element e defined in Manopt.jl, which can also directly be printed to an IO stream io. This method should generate a human readable summary of e.

By default, the variant with an IO stream dispatches to the one without to generate a string and prints it to the IO stream. If you implement the variant with the stream io, remember to also provide the one without.

The summary is meant to be used in different contexts:

  • :default refers to a (multiline) context in the REPL where a human should read a comprehensive summary of e. This is also the default.
  • :inline should be a shorter variant that can be used inline of other summaries, e.g. in lists
  • :short should be a form even shorter or equal to :inline, for example when in a list, a certain element, like a DebugAction can be represented by a symbol. The short variant should by default fall back to :inline.
source
Manopt.status_summary — Method
status_summary(io, e; context::Symbol = :default)
status_summary(e; context::Symbol = :default)

Return a string reporting about the current status of an element e defined in Manopt.jl, which can also directly be printed to an IO stream io. This method should generate a human readable summary of e.

By default, the variant with an IO stream dispatches to the one without to generate a string and prints it to the IO stream. If you implement the variant with the stream io, remember to also provide the one without.

The summary is meant to be used in different contexts:

  • :default refers to a (multiline) context in the REPL where a human should read a comprehensive summary of e. This is also the default.
  • :inline should be a shorter variant that can be used inline of other summaries, e.g. in lists
  • :short should be a form even shorter or equal to :inline, for example when in a list, a certain element, like a DebugAction can be represented by a symbol. The short variant should by default fall back to :inline.
source

Parameter

Within Manopt.jl a parameter is a value within a structure that can be accessed or set from outside. Since the overall design model is modular, get_parameter and set_parameter! allow to specify a certain “path” into a structure to get or set something.

For example the gradient of an objective function within a problem has a certain parameter like the LagrangianGradient used within the sub problem of the augmented_Lagrangian_method. The parameter functions allow to generically address such objects without having to care about decorators or in which field exactly the parameter is stored. This can for example also be used in connection with DebugWhenActive to deactivate debug output under certain circumstances.

While the functions can be called with symbols to specify the position of a parameter, internally, and more efficiently, Val(:Symbol)s are used.

Without a structure upfront, starting just with a symbol, properties of Manopt.jl itself can be set.

Manopt.get_parameter — Method
get_parameter(f, element::Symbol, args...)

Access arbitrary parameters from f addressed by a symbol element.

For any f and a Symbol element, dispatch on its value so that, by default, some element is obtained from f, potentially further qualified by args....

This function returns nothing if f does not have the property element.

source
Manopt.get_parameter — Method
get_parameter(element::Symbol; default=nothing)

Access global Manopt parameters addressed by a symbol element. This first dispatches on the value of element.

If the value is not set, default is returned.

The parameters are queried from the global settings using Preferences.jl, so they are persistent within your activated Environment, see also set_parameter!.

Currently used settings

  • :Mode: the mode can be set to "Tutorial" to get several hints, especially in scenarios where the optimization on manifolds is different from the usual “experience” in (classical, Euclidean) optimization. Any other value has the same effect as not setting it.

  • :KeywordsErrorMode: specify how to handle the case when unknown keywords are passed to a solver. Since solvers often pass their keywords on to internal structures, to for example decorate the objective or the state, checking keywords has its own method in Manopt.jl. The following values are available:

    • "none" does not report anything and the keyword is just ignored
    • "warn" issues a warning (default)
    • "error" throws a ManoptKeywordError

    All other values are treated the same as "none".

source
Manopt.set_parameter! — Method
set_parameter!(f, element::Symbol, args...)

For any f and a Symbol element, dispatch on its value so that, by default, some args... are set in f or in one of its sub elements.

By default this calls set_parameter!(f, Val(element), args...) to dispatch on the value of the symbol.

source
Manopt.set_parameter! — Method
set_parameter!(element::Symbol, value::Union{String,Bool,<:Number})

Set global Manopt parameters addressed by a symbol element.

This first dispatches on the value of element.

The parameters are stored to the global settings using Preferences.jl.

Passing a value of "" deletes the corresponding entry from the preferences. Whenever the LocalPreferences.toml is modified, this is also issued as an @info.

source