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
— TypeAbstractManoptSolverState
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
p
a point on a manifold with the current iteratestop
aStoppingCriterion
.
Manopt.get_state
— Functionget_state(s::AbstractManoptSolverState)
return the undecorated AbstractManoptSolverState
of the (possibly) decorated s
. As long as your decorated state store the state within s.state
and the dispatch_state_decorator
is set to Val{true}
, the internal state are extracted.
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
— Functionget_iterate(O::AbstractManoptSolverState)
return the (last stored) iterate within AbstractManoptSolverState
s`. By default also undecorates the state beforehand.
get_iterate(agst::AbstractGradientSolverState)
return the iterate stored within gradient options. THe default resturns agst.p
.
Manopt.set_iterate!
— Functionset_iterate!(s::AbstractManoptSolverState, M::AbstractManifold, p)
set the iterate within an AbstractManoptSolverState
to some (start) value p
.
set_iterate!(agst::AbstractGradientSolverState, M, p)
set the (current) iterate stored within an AbstractGradientSolverState
to p
. The default function modifies s.p
.
Manopt.get_gradient
— Methodget_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.
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.
X = get_gradient(M::AbstractManifold, p::ManifoldAlternatingGradientObjective, p, k)
get_gradient!(M::AbstractManifold, p::ManifoldAlternatingGradientObjective, X, p, k)
Evaluate one of the component gradients $\operatorname{grad}f_k$, $k∈\{1,…,n\}$, at x
(in place of Y
).
Manopt.set_gradient!
— Functionset_gradient!(s::AbstractManoptSolverState, M::AbstractManifold, p, X)
set the gradient within an (possibly decorated) AbstractManoptSolverState
to some (start) value X
in the tangent space at p
.
set_gradient!(agst::AbstractGradientSolverState, M, p, X)
set the (current) gradient stored within an AbstractGradientSolverState
to X
. The default function modifies s.X
.
Decorators for AbstractManoptSolverState
A solver state can be decorated using the following trait and function to initialize
Manopt.dispatch_state_decorator
— Functiondispatch_state_decorator(s::AbstractManoptSolverState)
Indicate internally, whether an AbstractManoptSolverState
s
to be of decorating type, i.e. it stores (encapsulates) 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.
Manopt.is_state_decorator
— Functionis_state_decorator(s::AbstractManoptSolverState)
Indicate, whether AbstractManoptSolverState
s
are of decorator type.
Manopt.decorate_state!
— Functiondecorate_state!(s::AbstractManoptSolverState)
decorate the AbstractManoptSolverState
s
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 theDebugSolverState
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.return_state
- (false
) indicate whether to wrap the options in aReturnSolverState
, indicating that the solver should return options and not (only) the minimizer.
other keywords are ignored.
See also
A simple example is the
Manopt.ReturnSolverState
— TypeReturnSolverState{O<:AbstractManoptSolverState} <: AbstractManoptSolverState
This internal type is used to indicate that the contained AbstractManoptSolverState
state
should be returned at the end of a solver instead of the usual minimizer.
See also
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.
Manopt.AbstractStateAction
— TypeAbstractStateAction
a common Type
for AbstractStateActions
that might be triggered in decoraters, for example within the DebugSolverState
or within the RecordSolverState
.
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
— TypeStoreStateAction <: AbstractStateAction
internal storage for AbstractStateAction
s to store a tuple of fields from an AbstractManoptSolverState
s
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 certainSymbols
keys
– anNTuple
ofSymbols
to refer to fields ofAbstractManoptSolverState
once
– whether to update the internal values only once per iterationlastStored
– last iterate, where thisAbstractStateAction
was called (to determineonce
Constructiors
AbstractStateAction([keys=(), once=true])
Initialize the Functor to an (empty) set of keys, where once
determines whether more that one update per iteration are effective
AbstractStateAction(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 AbstractStateAction
a
at the Symbol
key
.
Manopt.has_storage
— Functionget_storage(a,key)
return whether the AbstractStateAction
a
has a value stored at the Symbol
key
.
Manopt.update_storage!
— Functionupdate_storage!(a, s)
update the AbstractStateAction
a
internal values to the ones given on the AbstractManoptSolverState
s
.
update_storage!(a, d)
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.
Abstract States
In a few cases it is useful to have a hierarchy of types. These are
Manopt.AbstractSubProblemSolverState
— TypeAbstractSubProblemSolverState <: AbstractManoptSolverState
An abstract type for problems that involve a subsolver
Manopt.AbstractGradientSolverState
— TypeAbstractGradientSolverState <: AbstractManoptSolverState
A generic AbstractManoptSolverState
type for gradient based options data.
It assumes that
- the iterate is stored in the field
p
- the gradient at
p
is stored inX
.
see also
GradientDescentState
, StochasticGradientDescentState
, SubGradientMethodState
, QuasiNewtonState
.
Manopt.AbstractHessianSolverState
— TypeAbstractHessianSolverState <: AbstractGradientSolverState
An AbstractManoptSolverState
type to represent algorithms that employ the Hessian. These options are assumed to have a field (gradient
) to store the current gradient $\operatorname{grad}f(x)$
Manopt.AbstractPrimalDualSolverState
— TypeAbstractPrimalDualSolverState
A general type for all primal dual based options to be used within primal dual based algorithms