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.Options
— TypeOptions
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
x
a point with the current iteratestop
aStoppingCriterion
.
Manopt.get_options
— Functionget_options(o::Options)
return the undecorated Options
of the (possibly) decorated o
. As long as your decorated options store the options within o.options
and the dispatch_options_decorator
is set to Val{true}
, the internal options are extracted.
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_decorator
— Functiondispatch_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.
Manopt.is_options_decorator
— Functionis_options_decorator(o::Options)
Indicate, whether Options
o
are of decorator type.
Manopt.decorate_options
— Functiondecorate_options(o)
decorate the Options
o
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 representingDebugAction
s,Strings
used as dividers and a subsampling integer. These are passed as aDebugGroup
within:All
to theDebugOptions
decorator dictionary. Only excention is:Stop
that is passed to:Stop
.record
– (Array{Union{Symbol,RecordAction,Int},1}()
) specify recordings by usingSymbol
s orRecordAction
s directly. The integer can again be used for only recording every $i$th iteration.
See also
In general decorators often perform actions so we introduce
Manopt.AbstractOptionsAction
— TypeAbstractOptionsAction
a common Type
for AbstractOptionsActions
that might be triggered in decoraters, for example DebugOptions
or RecordOptions
.
as well as a helper for storing values using keys, i.e.
Manopt.StoreOptionsAction
— TypeStoreTupleAction <: AbstractOptionsAction
internal storage for AbstractOptionsAction
s to store a tuple of fields from an Options
s
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 certainSymbols
keys
– anNTuple
ofSymbols
to refer to fields ofOptions
once
– whether to update the internal values only once per iterationlastStored
– last iterate, where thisAbstractOptionsAction
was called (to determineonce
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.
Manopt.get_storage
— Functionget_storage(a,key)
return the internal value of the StoreOptionsAction
a
at the Symbol
key
.
Manopt.has_storage
— Functionget_storage(a,key)
return whether the StoreOptionsAction
a
has a value stored at the Symbol
key
.
Manopt.update_storage!
— Functionupdate_storage!(a,o)
update the StoreOptionsAction
a
internal values to the ones given on the Options
o
.
update_storage!(a,o)
update the StoreOptionsAction
a
internal values to the ones given in the dictionary d
. The values are merged, where the values from d
are preferred.
Debug Options
Manopt.DebugAction
— TypeDebugAction
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
.
Manopt.DebugChange
— TypeDebugChange()
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 actionprefix
– ("Last Change:"
) prefix of the debug output (ignored if you setformat
)io
– (stdout
) default steream to print the debug to.format
- ("$prefix %f"
) format to print the output using an sprintf format.
Manopt.DebugCost
— TypeDebugCost <: 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 (seelong
).io
– (stdout
) default steream to print the debug to.long
- (false
) short form to set the format toF(x):
(default) orcurrent cost:
and the cost
Manopt.DebugDivider
— TypeDebugDivider <: DebugAction
print a small div
ider (default " | "
).
Constructor
DebugDivider(div,print)
Manopt.DebugEntry
— TypeDebugEntry <: 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 withinOptions
Constructor
DebugEntry(f[, prefix="$f:", format = "$prefix %s", io=stdout])
Manopt.DebugEntryChange
— TypeDebugEntryChange{T} <: DebugAction
print a certain entries change during iterates
Additional Fields
print
– (print
) function to print the resultprefix
– ("Change of :x"
) prefix to the print outformat
– ("$prefix %e"
) format to print (uses the `prefix by default and scientific notation)field
– Symbol the field can be accessed with withinOptions
distance
– function (p,o,x1,x2) to compute the change/distance between two values of the entrystorage
– aStoreOptionsAction
to store the previous value of:f
Constructors
DebugEntryChange(f,d)
Keyword arguments
io
(stdout
) anIOStream
prefix
("Change of $f"
)storage
(StoreOptionsAction((f,))
) aStoreOptionsAction
initial_value
an initial value for the change ofo.field
.format
– ("$prefix %e"
) format to print the change
Manopt.DebugEvery
— TypeDebugEvery <: 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.
Manopt.DebugGroup
— TypeDebugGroup <: DebugAction
group a set of DebugAction
s 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 DebugAction
s 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
Manopt.DebugIterate
— TypeDebugIterate <: 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 printx:
orcurrent iterate
Manopt.DebugIteration
— TypeDebugIteration <: 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 )
Manopt.DebugOptions
— TypeDebugOptions <: Options
The debug options append to any options a debug functionality, i.e. they act as a decorator pattern. Internally a Dict
ionary 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 informationdebugDictionary
– aDict{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
ofDebugAction
s, then it is stored as adebugDictionary
within:All
. - a
Dict{Symbol,DebugAction}
. - an Array of Symbols, String and an Int for the
DebugFactory
Manopt.DebugStoppingCriterion
— TypeDebugStoppingCriterion <: DebugAction
print the Reason provided by the stopping criterion. Usually this should be empty, unless the algorithm stops.
Manopt.DebugWarnIfCostIncreases
— TypeDebugWarnIfCostIncreases <: 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:
Manopt.DebugActionFactory
— MethodDebugActionFactory(s)
create a DebugAction
where
- a
String
yields the correspoinding divider - a
DebugAction
is passed through - a [
Symbol
] createsDebugEntry
of that symbol, with the exceptions of:Change
,:Iterate
,:Iteration
, and:Cost
. - a
Tuple{Symbol,String}
creates aDebugEntry
of that symbol where the String specifies the format.
Manopt.DebugFactory
— MethodDebugFactory(a)
given an array of Symbol
s, String
s DebugAction
s and Ints
- The symbol
:Stop
creates an entry of to display the stopping criterion at the end (:Stop => DebugStoppingCriterion()
) - The symbol
:Cost
creates aDebugCost
- The symbol
:iteration
creates aDebugIteration
- The symbol
:Change
creates aDebugChange
- any other symbol creates debug output of the corresponding field in
Options
- any string creates a
DebugDivider
- any
DebugAction
is directly included - an Integer
k
introduces that debug is only printed everyk
th iteration
see DebugSolver for details on the decorated solver.
Further specific DebugAction
s can be found at the specific Options.
Record Options
Manopt.RecordAction
— TypeRecordAction
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
anArray
of the recorded values.
Manopt.RecordChange
— TypeRecordChange <: RecordAction
debug for the amount of change of the iterate (stored in o.x
of the Options
) during the last iteration.
Additional Fields
storage
aStoreOptionsAction
to store (at least)o.x
to use this as the last value (to compute the change)
Manopt.RecordCost
— TypeRecordCost <: RecordAction
record the current cost function value, see get_cost
.
Manopt.RecordEntry
— TypeRecordEntry{T} <: RecordAction
record a certain fields entry of type {T} during the iterates
Fields
recorded_values
– the recorded Iteratesfield
– Symbol the entry can be accessed with withinOptions
Manopt.RecordEntryChange
— TypeRecordEntryChange{T} <: RecordAction
record a certain entries change during iterates
Additional Fields
recorded_values
– the recorded Iteratesfield
– Symbol the field can be accessed with withinOptions
distance
– function (p,o,x1,x2) to compute the change/distance between two values of the entrystorage
– aStoreOptionsAction
to store (at least)getproperty(o, d.field)
Manopt.RecordEvery
— TypeRecordEvery <: 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
Manopt.RecordGroup
— TypeRecordGroup <: RecordAction
group a set of RecordAction
s into one action, where the internal RecordAction
s 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 RecordAction
s 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.
Manopt.RecordIterate
— TypeRecordIterate <: 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
.
Manopt.RecordIteration
— TypeRecordIteration <: RecordAction
record the current iteration
Manopt.RecordOptions
— TypeRecordOptions <: Options
append to any Options
the decorator with record functionality, Internally a Dict
ionary 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 informationrecordDictionary
– aDict{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
ofRecordAction
s, then it is stored as arecordDictionary
(@ref) within the dictionary at:All
. - a
Dict{Symbol,RecordAction}
.
Manopt.RecordActionFactory
— MethodRecordActionFactory(s)
create a RecordAction
where
- a
RecordAction
is passed through - a [
Symbol
] createsRecordEntry
of that symbol, with the exceptions of:Change
,:Iterate
,:Iteration
, and:Cost
.
Manopt.RecordFactory
— MethodRecordFactory(o::Options, a)
given an array of Symbol
s and RecordAction
s and Ints
- The symbol
:Cost
creates aRecordCost
- The symbol
:iteration
creates aRecordIteration
- The symbol
:Change
creates aRecordChange
- any other symbol creates a
RecordEntry
of the corresponding field inOptions
- any
RecordAction
is directly included - an semantic pair
:symbol => RecordAction
is directly included - an Integer
k
introduces that record is only performed everyk
th iteration
Manopt.get_record
— Functionget_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.
Manopt.get_record
— Methodget_record(r::RecordAction)
return the recorded values stored within a RecordAction
r
.
Manopt.get_record
— Methodget_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 i
th 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.
Manopt.get_record_action
— Functionget_record_action(o::Options, s::Symbol)
return the action contained in the (first) RecordOptions
decorator within the Options
o
.
Manopt.get_record_options
— Methodget_record_options(o::Options)
return the RecordOptions
among the decorators from the Options
o
Manopt.has_record
— Methodhas_record(o::Options)
check whether the Options
o
are decorated with RecordOptions
Base.getindex
— Methodget_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...]
.
Base.getindex
— Methodgetindex(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.
see RecordSolver for details on the decorated solver.
Further specific RecordAction
s 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!
— Functionrecord_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.