Edit on GitHub

The Solver State

Given an AbstractManoptProblem, that is a certain optimisation task, the state specifies the solver to use. It contains the parameters of a solver and all fields necessary during the algorithm, e.g. the current iterate, a StoppingCriterion or a Stepsize.

Manopt.AbstractManoptSolverState — Type
AbstractManoptSolverState

A general super type for all solver states.

Fields

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

source
Manopt.get_count — Function
get_count(ams::AbstractManoptSolverState, ::Symbol)

Obtain the count for a certain countable size, e.g. the :Iterations. This function returns 0 if there was nothing to count

Available symbols from within the solver state

  • :Iterations is passed on to the stop field to obtain the iterataion at which the solver stopped.
source
get_count(co::ManifoldCountObjective, s::Symbol, mode::Symbol=:None)

Get the number of counts for a certain symbel s.

Depending on the mode different results appear if the symbol does not exist in the dictionary

  • :None – (default) silent mode, returns -1 for non-existing entries
  • :warn – issues a warning if a field does not exist
  • :error – issues an error if a field does not exist
source

Since every subtype of an AbstractManoptSolverState directly relate to a solver, the concrete states are documented together with the corresponding solvers. This page documents the general functionality available for every state.

A first example is to access, i.e. obtain or set, the current iterate. This might be useful to continue investigation at the current iterate, or to set up a solver for a next experiment, respectively.

Manopt.get_iterate — Function
get_iterate(O::AbstractManoptSolverState)

return the (last stored) iterate within AbstractManoptSolverStates`. By default also undecorates the state beforehand.

source
get_iterate(agst::AbstractGradientSolverState)

return the iterate stored within gradient options. THe default resturns agst.p.

source
Manopt.get_gradient — Method
get_gradient(M::AbstractManifold, sgo::ManifoldStochasticGradientObjective, p, k)
get_gradient!(M::AbstractManifold, sgo::ManifoldStochasticGradientObjective, Y, p, k)

Evaluate one of the summands gradients $\operatorname{grad}f_k$, $k∈\{1,…,n\}$, at x (in place of Y).

If you use a single function for the stochastic gradient, that works inplace, then get_gradient is not available, since the length (or number of elements of the gradient required for allocation) can not be determined.

source
get_gradient(M::AbstractManifold, sgo::ManifoldStochasticGradientObjective, p)
get_gradient!(M::AbstractManifold, sgo::ManifoldStochasticGradientObjective, X, p)

Evaluate the complete gradient $\operatorname{grad} f = \displaystyle\sum_{i=1}^n \operatorname{grad} f_i(p)$ at p (in place of X).

If you use a single function for the stochastic gradient, that works inplace, then get_gradient is not available, since the length (or number of elements of the gradient required for allocation) can not be determined.

source

An internal function working on the state and elements within a state is used to pass messages from (sub) activties of a state to the corresponding DebugMessages

Manopt.get_message — Function
get_message(du::AbstractManoptSolverState)

get a message (String) from e.g. performing a step computation. This should return any message a sub-step might have issued

source

Decorators for AbstractManoptSolverState

A solver state can be decorated using the following trait and function to initialize

Manopt.dispatch_state_decorator — Function
dispatch_state_decorator(s::AbstractManoptSolverState)

Indicate internally, whether an AbstractManoptSolverState s to be of decorating type, i.e. it stores (encapsulates) a state in itself, by default in the field s.state.

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

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

source
Manopt.decorate_state! — Function
decorate_state!(s::AbstractManoptSolverState)

decorate the AbstractManoptSolverStates 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 DebugSolverState 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.
  • return_state - (false) indicate whether to wrap the options in a ReturnSolverState, indicating that the solver should return options and not (only) the minimizer.

other keywords are ignored.

See also

DebugSolverState, RecordSolverState, ReturnSolverState

source

A simple example is the

as well as DebugSolverState and RecordSolverState.

State Actions

A state action is a struct for callback functions that can be attached within for example the just mentioned debug decorator or the record decorator.

Several state decorators or actions might store intermediate values like the (last) iterate to compute some change or the last gradient. In order to minimise the storage of these, there is a generic StoreStateAction that acts as generic common storage that can be shared among different actions.

Manopt.StoreStateAction — Type
StoreStateAction <: AbstractStateAction

internal storage for AbstractStateActions to store a tuple of fields from an AbstractManoptSolverStates

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

Fields

  • values – a dictionary to store interims values based on certain Symbols
  • keys – a Vector of Symbols to refer to fields of AbstractManoptSolverState
  • point_values – a NamedTuple of mutable values of points on a manifold to be stored in StoreStateAction. Manifold is later determined by AbstractManoptProblem passed to update_storage!.
  • point_init – a NamedTuple of boolean values indicating whether a point in point_values with matching key has been already initialized to a value. When it is false, it corresponds to a general value not being stored for the key present in the vector keys.
  • vector_values – a NamedTuple of mutable values of tangent vectors on a manifold to be stored in StoreStateAction. Manifold is later determined by AbstractManoptProblem passed to update_storage!. It is not specified at which point the vectors are tangent but for storage it should not matter.
  • vector_init – a NamedTuple of boolean values indicating whether a tangent vector in vector_values with matching key has been already initialized to a value. When it is false, it corresponds to a general value not being stored for the key present in the vector keys.
  • once – whether to update the internal values only once per iteration
  • lastStored – last iterate, where this AbstractStateAction was called (to determine once)

To handle the general storage, use get_storage and has_storage with keys as Symbols. For the point storage use PointStorageKey. For tangent vector storage use VectorStorageKey. Point and tangent storage have been optimized to be more efficient.

Constructiors

StoreStateAction(s::Vector{Symbol})

This is equivalent as providing s to the keyword store_fields, just that here, no manifold is necessay for the construciton.

StoreStateAction(M)

Keyword arguments

  • store_fields (Symbol[])
  • store_points (Symbol[])
  • store_vectors (Symbol[])

as vectors of symbols each referring to fields of the state (lower case symbols) or semantic ones (upper case).

  • p_init (rand(M))
  • X_init (zero_vector(M, p_init))

are used to initialize the point and vector storages, change these if you use other types (than the default) for your points/vectors on M.

  • once (true) whether to update internal storage only once per iteration or on every update call
source
Manopt.get_storage — Function
get_storage(a::AbstractStateAction, key::Symbol)

Return the internal value of the AbstractStateAction a at the Symbol key.

source
get_storage(a::AbstractStateAction, ::PointStorageKey{key}) where {key}

Return the internal value of the AbstractStateAction a at the Symbol key that represents a point.

source
get_storage(a::AbstractStateAction, ::VectorStorageKey{key}) where {key}

Return the internal value of the AbstractStateAction a at the Symbol key that represents a vector vector.

source
Manopt.has_storage — Function
has_storage(a::AbstractStateAction, key::Symbol)

Return whether the AbstractStateAction a has a value stored at the Symbol key.

source
has_storage(a::AbstractStateAction, ::PointStorageKey{key}) where {key}

Return whether the AbstractStateAction a has a point value stored at the Symbol key.

source
has_storage(a::AbstractStateAction, ::VectorStorageKey{key}) where {key}

Return whether the AbstractStateAction a has a point value stored at the Symbol key.

source
Manopt.update_storage! — Function
update_storage!(a::AbstractStateAction, amp::AbstractManoptProblem, s::AbstractManoptSolverState)

Update the AbstractStateAction a internal values to the ones given on the AbstractManoptSolverState s. Optimized using the information from amp

source
update_storage!(a::AbstractStateAction, d::Dict{Symbol,<:Any})

Update the AbstractStateAction a internal values to the ones given in the dictionary d. The values are merged, where the values from d are preferred.

source

as well as two internal functions

Abstract States

In a few cases it is useful to have a hierarchy of types. These are