The Record decorator for solver states

RecordAction

A RecordAction is a small functor to record values. The usual call is given by

(amp::AbstractManoptProblem, ams::AbstractManoptSolverState, k) -> s

that performs the record for the current problem and solver combination, and where k is the current iteration.

By convention k=0 is interpreted as “for initialization only”: only initialize internal values, but do not trigger any record. Note that the record is called from within stop_solver!, which returns true afterwards.

Any negative value is interpreted as a “reset”, and should hence delete all stored recordings, for example when reusing a RecordAction. The start of a solver calls the :Iteration and :Stop dictionary entries with -1, to reset those recordings.

By default any RecordAction is assumed to record its values in a field recorded_values, an Vector of recorded values. See get_record(ra).

RecordEvery <: RecordAction

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

This method does not perform any record itself but relies on its children's methods.

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, a tuple per call of this group. The entries can be later addressed either by index or by semantic Symbols.

Constructors

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

Construct a group consisting of an Array of RecordActions g.

RecordGroup(g, symbols::Dict{Symbol,Int})

Additionally store a dictionary that maps Symbols to indices within g.

Examples

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

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

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

A RecordGroup to record the current iteration and the cost, which can then be accessed using get_record(g2, :Cost) or g2[:Cost].

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

A RecordGroup identical to the previous constructor, just a little easier to use. To access all recordings of the second entry of this last g3 you can do either g3[2] or g3[:Cost], the first one can only be accessed by g3[1], since no symbol was given here.

RecordSolverState <: AbstractManoptSolverState

Append to any AbstractManoptSolverState the decorator with record capability. 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 state can still be accessed using the get_state function.

Fields

• state: the state that is extended by record information
• recordDictionary: a NamedTuple of RecordActions to keep track of all different recorded values

Constructors

RecordSolverState(s, dR)

Construct a record decorated AbstractManoptSolverState, where dR can be

• a RecordAction, then it is stored within the dictionary at :Iteration.
• a Dict{Symbol,RecordAction}.
• an Array of RecordActions, Symbols and Strings, which is passed to the RecordFactory.
• a single Symbol, which is also passed to the RecordFactory.

RecordSubsolver <: RecordAction

Record the current sub solver's recording, by calling get_record on the sub state with the symbols stored in record.

Fields

• recorded_values: an array to store the recorded values
• record: arguments for get_record. Defaults to just one symbol :Iteration, but could be set to also record the :Stop action.

Constructor

RecordSubsolver(; record=:Iteration, record_type=eltype([]))

RecordWhenActive <: RecordAction

A record action that only records if the active boolean is set to true. This can be set from outside and is for example triggered by RecordEvery on recordings of a subsolver. While this is for sub solvers maybe not completely necessary, recording values that are never accessible, is not that useful.

Fields

• active: a boolean that can be (de-)activated from outside to turn recording on/off
• always_update: whether or not to call the inner record action with nonpositive iterations (init/reset)

Constructor

RecordWhenActive(r::RecordAction, active=true, always_update=true)

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 symbol s, the symbols from the tuple sT or the index i. See get_record for details.

getindex(rs::RecordSolverState, s::Symbol)
rs[s]

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

getindex(rs::RecordSolverState, s::Symbol, i...)rs[s, i...]

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

get_record(s::RecordSolverState[, symbol=:Iteration])

Return the recorded values from within the RecordSolverState s that were recorded with respect to the Symbol symbol as an Array. The default refers to any recordings during an :Iteration.

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

get_record(r::RecordAction)

Return the recorded values stored within a RecordAction r.

get_record(r::RecordGroup)

Return an array of tuples, where each tuple is a recorded set per iteration or record call.

get_record(r::RecordGroup, i)

Return an array of values corresponding to the $i$-th entry in this record group.

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

Return an array of recorded values with respect to the symbol 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.

get_record(s::RecordSolverState[, symbol=:Iteration], i...)

Return the recorded values from within the RecordSolverState s that were recorded with respect to the symbol symbol as an Array. The default refers to any recordings during an :Iteration.

The following arguments i... can be used to access further elements of that recording, either by an index i or by a further symbol addressing the recorded elements.

get_record_action(s::AbstractManoptSolverState, symbol::Symbol=:Iteration)

Return the action contained in the (first) RecordSolverState decorator within the AbstractManoptSolverState s.

get_record_state(s::AbstractManoptSolverState)

Return the RecordSolverState among the decorators of the AbstractManoptSolverState s.

has_record(s::AbstractManoptSolverState)

Indicate whether the AbstractManoptSolverState s is decorated with a RecordSolverState.

initialize_solver!(ams::AbstractManoptProblem, rss::RecordSolverState)

Extend the initialization of the solver by a hook to run records that were added to the :Start entry.

step_solver!(amp::AbstractManoptProblem, rss::RecordSolverState, k)

Extend the ith step of the solver by a hook to run records, that were added to the :Iteration entry.

stop_solver!(amp::AbstractManoptProblem, rss::RecordSolverState, k)

Extend the call to the stopping criterion by a hook to run records, that were added to the :Stop entry.

record_or_reset!(r, v, k)

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

set_parameter!(rss::RecordSolverState, ::Val{:Record}, args...)

Set certain values specified by args... into the elements of the recordDictionary.