Options

For most algorithms a certain set of options can either be generated beforehand of the function with keywords can be used. Generally the type

Manopt.OptionsType
Options

A general super type for all options.

Fields

The following fields are assumed to be default. If you use different ones, provide the access functions accordingly

source

Since the Options directly relate to a solver, they are documented with the corresponding solvers. You can always access the options (since they might be decorated) by calling get_options.

Decorators for Options

Options can be decorated using the following trait and function to initialize

Manopt.dispatch_options_decoratorFunction
dispatch_options_decorator(o::Options)

Indicate internally, whether an Options o to be of decorating type, i.e. it stores (encapsulates) options in itself, by default in the field o. options.

Decorators indicate this by returning Val{true} for further dispatch.

The default is Val{false}, i.e. by default an options is not decorated.

source
Manopt.decorate_optionsFunction
decorate_options(o)

decorate the Optionso with specific decorators.

Optional Arguments

optional arguments provide necessary details on the decorators. A specific one is used to activate certain decorators.

  • debug – (Array{Union{Symbol,DebugAction,String,Int},1}()) a set of symbols representing DebugActions, Strings used as dividers and a subsampling integer. These are passed as a DebugGroup within :All to the DebugOptions decorator dictionary. Only excention is :Stop that is passed to :Stop.
  • record – (Array{Union{Symbol,RecordAction,Int},1}()) specify recordings by using Symbols or RecordActions directly. The integer can again be used for only recording every $i$th iteration.

See also

DebugOptions, RecordOptions

source

In general decorators often perform actions so we introduce

as well as a helper for storing values using keys, i.e.

Manopt.StoreOptionsActionType
StoreTupleAction <: AbstractOptionsAction

internal storage for AbstractOptionsActions to store a tuple of fields from an Optionss

This functor posesses the usual interface of functions called during an iteration, i.e. acts on (p,o,i), where p is a Problem, o is an Options and i is the current iteration.

Fields

  • values – a dictionary to store interims values based on certain Symbols
  • keys – an NTuple of Symbols to refer to fields of Options
  • once – whether to update the internal values only once per iteration
  • lastStored – last iterate, where this AbstractOptionsAction was called (to determine once

Constructiors

StoreOptionsAction([keys=(), once=true])

Initialize the Functor to an (empty) set of keys, where once determines whether more that one update per iteration are effective

StoreOptionsAction(keys, once=true])

Initialize the Functor to a set of keys, where the dictionary is initialized to be empty. Further, once determines whether more that one update per iteration are effective, otherwise only the first update is stored, all others are ignored.

source

Debug Options

Manopt.DebugActionType
DebugAction

A DebugAction is a small functor to print/issue debug output. The usual call is given by (p,o,i) -> s that performs the debug based on a Problem p, Options o and the current iterate i.

By convention i=0 is interpreted as "For Initialization only", i.e. only debug info that prints initialization reacts, i<0 triggers updates of variables internally but does not trigger any output. Finally typemin(Int) is used to indicate a call from stop_solver! that returns true afterwards.

Fields (assumed by subtypes to exist)

  • print method to perform the actual print. Can for example be set to a file export,

or to @info. The default is the print function on the default Base.stdout.

source
Manopt.DebugChangeType
DebugChange()

debug for the amount of change of the iterate (stored in o.x of the Options) during the last iteration. See DebugEntryChange for the general case

Keyword Parameters

  • storage – (StoreOptionsAction( (:x,) )) – (eventually shared) the storage of the previous action
  • prefix – ("Last Change:") prefix of the debug output (ignored if you set format)
  • io – (stdout) default steream to print the debug to.
  • format - ( "$prefix %f") format to print the output using an sprintf format.
source
Manopt.DebugCostType
DebugCost <: DebugAction

print the current cost function value, see get_cost.

Constructors

DebugCost()

Parameters

  • format - ("$prefix %f") format to print the output using sprintf and a prefix (see long).
  • io – (stdout) default steream to print the debug to.
  • long - (false) short form to set the format to F(x): (default) or current cost: and the cost
source
Manopt.DebugDividerType
DebugDivider <: DebugAction

print a small divider (default " | ").

Constructor

DebugDivider(div,print)
source
Manopt.DebugEntryType
DebugEntry <: RecordAction

print a certain fields entry of type {T} during the iterates, where a format can be specified how to print the entry.

Addidtional Fields

  • field – Symbol the entry can be accessed with within Options

Constructor

DebugEntry(f[, prefix="$f:", format = "$prefix %s", io=stdout])
source
Manopt.DebugEntryChangeType
DebugEntryChange{T} <: DebugAction

print a certain entries change during iterates

Additional Fields

  • print – (print) function to print the result
  • prefix – ("Change of :x") prefix to the print out
  • format – ("$prefix %e") format to print (uses the `prefix by default and scientific notation)
  • field – Symbol the field can be accessed with within Options
  • distance – function (p,o,x1,x2) to compute the change/distance between two values of the entry
  • storage – a StoreOptionsAction to store the previous value of :f

Constructors

DebugEntryChange(f,d)

Keyword arguments

  • io (stdout) an IOStream
  • prefix ("Change of $f")
  • storage (StoreOptionsAction((f,))) a StoreOptionsAction
  • initial_value an initial value for the change of o.field.
  • format – ("$prefix %e") format to print the change
source
Manopt.DebugEveryType
DebugEvery <: DebugAction

evaluate and print debug only every $i$th iteration. Otherwise no print is performed. Whether internal variables are updates is determined by alwaysUpdate.

This method does not perform any print itself but relies on it's childrens print.

source
Manopt.DebugGroupType
DebugGroup <: DebugAction

group a set of DebugActions into one action, where the internal prints are removed by default and the resulting strings are concatenated

Constructor

DebugGroup(g)

construct a group consisting of an Array of DebugActions g, that are evaluated en bloque; the method does not perform any print itself, but relies on the internal prints. It still concatenates the result and returns the complete string

source
Manopt.DebugIterateType
DebugIterate <: DebugAction

debug for the current iterate (stored in o.x).

Constructor

DebugIterate()

Parameters

  • io – (stdout) default steream to print the debug to.
  • long::Bool whether to print x: or current iterate
source
Manopt.DebugIterationType
DebugIteration <: DebugAction

Constructor

DebugIteration()

Keyword parameters

  • format - ("# %-6d") format to print the output using an sprintf format.
  • io – (stdout) default steream to print the debug to.

debug for the current iteration (prefixed with # by )

source
Manopt.DebugOptionsType
DebugOptions <: Options

The debug options append to any options a debug functionality, i.e. they act as a decorator pattern. Internally a Dictionary is kept that stores a DebugAction for several occasions using a Symbol as reference. The default occasion is :All and for example solvers join this field with :Start, :Step and :Stop at the beginning, every iteration or the end of the algorithm, respectively

The original options can still be accessed using the get_options function.

Fields (defaults in brackets)

  • options – the options that are extended by debug information
  • debugDictionary – a Dict{Symbol,DebugAction} to keep track of Debug for different actions

Constructors

DebugOptions(o,dA)

construct debug decorated options, where dD can be

  • a DebugAction, then it is stored within the dictionary at :All
  • an Array of DebugActions, then it is stored as a debugDictionary within :All.
  • a Dict{Symbol,DebugAction}.
  • an Array of Symbols, String and an Int for the DebugFactory
source
Manopt.DebugStoppingCriterionType
DebugStoppingCriterion <: DebugAction

print the Reason provided by the stopping criterion. Usually this should be empty, unless the algorithm stops.

source
Manopt.DebugWarnIfCostIncreasesType
DebugWarnIfCostIncreases <: DebugAction

print a warning if the cost increases.

Note that this provides an additional warning for gradient descent with its default constant step size.

Constructor

DebugWarnIfCostIncreases(warn=:Always; tol=1e-13)

Initialize the warning to warn :Always and introduce a tolerance for the test of 1e-13.

This can be set to :Once to only warn the first time the cost increases. It can also be set to :No to deactivate the warning, but this makes this Action also useless. All other symbols are handled as if they were :Always:

source
Manopt.DebugActionFactoryMethod
DebugActionFactory(s)

create a DebugAction where

  • a Stringyields the correspoinding divider
  • a DebugAction is passed through
  • a [Symbol] creates DebugEntry of that symbol, with the exceptions of :Change, :Iterate, :Iteration, and :Cost.
  • a Tuple{Symbol,String} creates a DebugEntry of that symbol where the String specifies the format.
source
Manopt.DebugFactoryMethod
DebugFactory(a)

given an array of Symbols, Strings DebugActions and Ints

  • The symbol :Stop creates an entry of to display the stopping criterion at the end (:Stop => DebugStoppingCriterion())
  • The symbol :Cost creates a DebugCost
  • The symbol :iteration creates a DebugIteration
  • The symbol :Change creates a DebugChange
  • any other symbol creates debug output of the corresponding field in Options
  • any string creates a DebugDivider
  • any DebugAction is directly included
  • an Integer kintroduces that debug is only printed every kth iteration
source

see DebugSolver for details on the decorated solver.

Further specific DebugActions can be found at the specific Options.

Record Options

Manopt.RecordActionType
RecordAction

A RecordAction is a small functor to record values. The usual call is given by (p,o,i) -> s that performs the record based on a Problem p, Options o and the current iterate i.

By convention i<=0 is interpreted as "For Initialization only", i.e. only initialize internal values, but not trigger any record, the same holds for i=typemin(Inf) which is used to indicate stop, i.e. that the record is called from within stop_solver! which returns true afterwards.

Fields (assumed by subtypes to exist)

  • recorded_values an Array of the recorded values.
source
Manopt.RecordChangeType
RecordChange <: RecordAction

debug for the amount of change of the iterate (stored in o.x of the Options) during the last iteration.

Additional Fields

  • storage a StoreOptionsAction to store (at least) o.x to use this as the last value (to compute the change)
source
Manopt.RecordEntryType
RecordEntry{T} <: RecordAction

record a certain fields entry of type {T} during the iterates

Fields

  • recorded_values – the recorded Iterates
  • field – Symbol the entry can be accessed with within Options
source
Manopt.RecordEntryChangeType
RecordEntryChange{T} <: RecordAction

record a certain entries change during iterates

Additional Fields

  • recorded_values – the recorded Iterates
  • field – Symbol the field can be accessed with within Options
  • distance – function (p,o,x1,x2) to compute the change/distance between two values of the entry
  • storage – a StoreOptionsAction to store (at least) getproperty(o, d.field)
source
Manopt.RecordEveryType
RecordEvery <: RecordAction

record only every $i$th iteration. Otherwise (optionally, but activated by default) just update internal tracking values.

This method does not perform any record itself but relies on it's childrens methods

source
Manopt.RecordGroupType
RecordGroup <: RecordAction

group a set of RecordActions into one action, where the internal RecordActions act independently, but the results can be collected in a grouped fashion, i.e. tuples per calls of this group. The enries can be later addressed either by index or semantic Symbols

Constructors

RecordGroup(g::Array{<:RecordAction, 1})

construct a group consisting of an Array of RecordActions g,

RecordGroup(g, symbols)

Examples

r = RecordGroup([RecordIteration(), RecordCost()])

A RecordGroup to record the current iteration and the cost. The cost can then be accessed using get_record(r,2) or r[2].

r = RecordGroup([RecordIteration(), RecordCost()], Dict(:Cost => 2))

A RecordGroup to record the current iteration and the cost, wich can then be accesed using get_record(:Cost) or r[:Cost].

r = RecordGroup([RecordIteration(), :Cost => RecordCost()])

A RecordGroup identical to the previous constructor, just a little easier to use.

source
Manopt.RecordIterateType
RecordIterate <: RecordAction

record the iterate

Constructors

RecordIterate(x0)

initialize the iterate record array to the type of x0, e.g. your initial data.

RecordIterate(P)

initialize the iterate record array to the data type T.

source
Manopt.RecordOptionsType
RecordOptions <: Options

append to any Options the decorator with record functionality, Internally a Dictionary is kept that stores a RecordAction for several concurrent modes using a Symbol as reference. The default mode is :Iteration, which is used to store information that is recorded during the iterations. RecordActions might be added to :Start or :Stop to record values at the beginning or for the stopping time point, respectively

The original options can still be accessed using the get_options function.

Fields

  • options – the options that are extended by debug information
  • recordDictionary – a Dict{Symbol,RecordAction} to keep track of all different recorded values

Constructors

RecordOptions(o,dR)

construct record decorated Options, where dR can be

  • a RecordAction, then it is stored within the dictionary at :Iteration
  • an Array of RecordActions, then it is stored as a recordDictionary(@ref) within the dictionary at :All.
  • a Dict{Symbol,RecordAction}.
source
Manopt.get_recordFunction
get_record(o::Options, [,s=:Iteration])
get_record(o::RecordOptions, [,s=:Iteration])

return the recorded values from within the RecordOptions o that where recorded with respect to the Symbol s as an Array. The default refers to any recordings during an :Iteration.

When called with arbitrary Options, this method looks for the RecordOptions decorator and calls get_record on the decorator.

source
Manopt.get_recordMethod
get_record(r::RecordGroup)

return an array of tuples, where each tuple is a recorded set, e.g. per iteration / record call.

get_record(r::RecordGruop, i::Int)

return an array of values corresponding to the ith entry in this record group

get_record(r::RecordGruop, s::Symbol)

return an array of recorded values with respect to the s, see RecordGroup.

get_record(r::RecordGroup, s1::Symbol, s2::Symbol,...)

return an array of tuples, where each tuple is a recorded set corresponding to the symbols s1, s2,... per iteration / record call.

source
Base.getindexMethod
get_index(ro::RecordOptions, s::Symbol)
ro[s]

Get the recorded values for reording type s, see get_record for details.

get_index(ro::RecordOptions, s::Symbol, i...)
ro[s, i...]

Acces the recording type of type s and call its RecordAction with [i...].

source
Base.getindexMethod
getindex(r::RecordGroup, s::Symbol)
r[s]
getindex(r::RecordGroup, sT::NTuple{N,Symbol})
r[sT]
getindex(r::RecordGroup, i)
r[i]

return an array of recorded values with respect to the s, the symbols from the tuple sT or the index i. See get_record for details.

source

see RecordSolver for details on the decorated solver.

Further specific RecordActions can be found at the specific Options.

there's one internal helper that might be useful for you own actions, namely

Manopt.record_or_reset!Function
record_or_reset!(r,v,i)

either record (i>0 and not Inf) the value v within the RecordAction r or reset (i<0) the internal storage, where v has to match the internal value type of the corresponding Recordaction.

source