Keyword handling

For the high-level interfaces Manopt.jl has an internal system to keep track of accepted keywords. The kwargs... are passed to at least the solver state and the state decorators.

The methods on this page keep track of where keywords are passed to and issue a warning if a keyword stays “unused”.

Manopt.ManoptKeywordError — Type

ManoptKeywordError <: Exception

An error to indicate that a certain function received keywords it does not accept.

Fields

f: the function that received the keywords
kw::Keywords: the keywords that were not accepted

Constructor

ManoptKeywordError(f, kw::Keywords)

source

Manopt.accepted_keywords — Method

accepted_keywords(problem)
accepted_keywords(objective)
accepted_keywords(solver)
accepted_keywords(stepsize)

Return the set of keywords, see Keywords, that a certain element of Manopt.jl accepts when constructed.

This function uses direct_keywords to find keywords a function directly accepts, and calls_with_kwargs to find functions it passes keywords to, where they also might be accepted. In order for a nonmutating function f to accept the same keywords as its mutating variant f!, one should set calls_with_kwargs(f) = (f!,).

This also includes keywords that are passed on to internal structures, which are specified using calls_with_kwargs as well.

source

Internal structures and functions

Manopt.Keywords — Type

Keywords

A small internal struct to represent a set of keywords.

The type parameter I stores the function the keywords belong to, or nothing if they are not associated with a certain function.

Fields

accepted::Set{Symbol}: symbols of keywords a certain function accepts
deprecated::Set{Symbol}: symbols of keywords a certain function has deprecated
origins::Dict{Symbol,Vector{Any}}: a dictionary that specifies for every keyword the function it is passed to. This usually should point to the function it is directly passed to.

Constructor

Keywords(    accepted=Set{Symbol}(), deprecated=Set{Symbol}();    from=nothing, origins=nothing)

Generate a Keywords wrapper, where both sets default to being empty.

Keyword arguments

from=nothing: the function the keywords (directly or indirectly) come from or are accepted in; it becomes the type parameter I. Use nothing to indicate that these are not associated with a certain function.
origins=nothing: an existing origins dictionary to extend; only used when from is given.

source

Manopt.add! — Method

add!(kw::Keywords, kw2::Keywords)

Append the Keywords kw2 to kw, that is, union the accepted and deprecated keywords as well as their origins, but keep the type parameter of kw. Origins already present in kw take precedence.

source

Manopt.calls_with_kwargs — Method

calls_with_kwargs(f)

Return a tuple of functions f calls and passes its kwargs... to.

source

Manopt.direct_keywords — Method

direct_keywords(problem)
direct_keywords(objective)
direct_keywords(solver)
direct_keywords(stepsize)

Return a set of keywords a function would directly work with.

source

Manopt.keywords_accepted — Function

keywords_accepted(f, mode=Symbol(get_parameter(:KeywordsErrorMode)), kw::Keywords=accepted_keywords(f); kwargs...)

Given a function f and the Keywords kw it accepts, check whether kwargs... are accepted by those keywords and warn if deprecated keywords are passed.

For keywords that are not accepted, the mode argument specifies how to report the result: :warn issues a warning, :error throws a ManoptKeywordError, and any other value (for example :none) neither warns nor errors. The default is taken from the :KeywordsErrorMode setting, see get_parameter.

source